# Webhook

Os webhooks permitem que seu sistema receba notificações automáticas sobre eventos importantes na plataforma da Pix One. Isso elimina a necessidade de consultar a API constantemente para verificar mudanças de status.

## Como Funcionam os Webhooks

​Quando um evento ocorre na Pix One (como uma transação aprovada ou uma nova transação criada), nosso sistema envia uma requisição HTTP POST para uma URL que você definiu, contendo informações detalhadas sobre o evento.

## Configuração de Webhooks

Para configurar webhooks, acesse seu painel na Pix One:

1. Navegue até **Webhook**
2. Insira a URL de destino para receber as notificações
3. Selecione os eventos que deseja monitorar

{% hint style="info" %}
Sua URL de webhook deve estar acessível publicamente na internet para receber as notificações.
{% endhint %}

## Modelo de Webhook

A Pix One utiliza o seguinte modelo padrão de envio para webhooks:

```json
{
  "id": "string",
  "type": "transaction",
  "transaction": "url",
  "data": {
    "object": {
      "id": "string",
      "ip": "string | null",
      "fee": {
        "netAmount": "number",
        "fixedAmount": "number",
        "estimatedFee": "number",
        "spreadPercentage": "number"
      },
      "pix": {
        "qrcode": "string"
      },
      "items": [
        {
          "id": "integer",
          "title": "string",
          "saleId": "integer",
          "physical": "boolean",
          "quantity": "integer",
          "createdAt": "date-time",
          "productId": "integer | null",
          "unitPrice": "number",
          "productImg": "integer | null",
          "externalRef": "integer | null",
          "productDesc": "integer | null",
          "productFile": "integer | null",
          "productName": "integer | null",
          "productPage": "integer | null",
          "productType": "integer | null",
          "productBanner": "integer | null"
        }
      ],
      "amount": "number",
      "boleto": {
        "url": "string",
        "barcode": "string",
        "paidAt": "date-time | null"
      },
      "refundedAt": "date-time | null",
      "status": "paid | processing | pending | approved | refused | chargedback | refunded | cancelled | chargeback",
      "customer": {
        "id": "string",
        "name": "string",
        "email": "string",
        "phone": "string",
        "address": {
          "id": "integer",
          "fee": "number",
          "saleId": "integer",
          "street": "string",
          "tracking": "integer | null",
          "steetCity": "string",
          "streetState": "string",
          "streetNumber": "string",
          "streetCountry": "integer | null",
          "streetZipCode": "string",
          "tracking_code": "integer | null",
          "tracking_status": "string",
          "streetComplement": "string",
          "streetNeighborhood": "string"
        },
        "document": {
          "type": "string",
          "number": "string"
        }
      },
      "delivery": {
        "status": "string",
        "createdAt": "date-time",
        "trackingCode": "string | null"
      },
      "metadata": "object | null",
      "secureId": "string",
      "companyId": "string",
      "tenant": "string",
      "traceable": "boolean",
      "paidAmount": "number",
      "externalRef": "string | null",
      "postbackUrl": "string",
      "installments": "integer",
      "paymentMethod": "string",
      "refusedReason": "string | null",
      "splits": [
        {
          "Type": "object"
        }
      ],
      "refunds": [
        {
          "Type": "object"
        }
      ],
      "refundedAmount": "number",
      "createdAt": "date-time"
    }
  }
}
```

## Eventos Disponíveis

A Pix One oferece os seguintes eventos para webhooks:

| Evento                  | Descrição                           |
| ----------------------- | ----------------------------------- |
| transaction.paid        | Um pagamento foi confirmado         |
| transaction.processing  | Uma transação está em processamento |
| transaction.pending     | Uma transação está pendente         |
| transaction.approved    | Uma transação foi aprovada          |
| transaction.refused     | Uma transação foi recusada          |
| transaction.chargedback | Uma transação sofreu chargeback     |
| transaction.refunded    | Uma transação foi reembolsada       |
| transaction.cancelled   | Uma transação foi cancelada         |

## Política de Retentativas

Se seu endpoint retornar um código diferente de 200 ou não responder dentro de 10 segundos, a Pix One seguirá uma política de retentativas:

* 1ª retentativa: 1 minuto após a falha
* 2ª retentativa: 5 minutos após a falha
* 3ª retentativa: 30 minutos após a falha
* 4ª retentativa: 2 horas após a falha
* 5ª retentativa: 6 horas após a falha

Após cinco tentativas sem sucesso, o webhook será marcado como falho e não será reenviado automaticamente.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pixone.com.br/outros/webhook.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.