> For the complete documentation index, see [llms.txt](https://docs.pixone.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pixone.com.br/outros/webhook.md).

# 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.