> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kavropay.online/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks & Notificações em Tempo Real

> Receba notificações automáticas de pagamento instantaneamente no seu servidor.

Assim que o cliente paga o PIX no banco dele, nosso servidor envia uma requisição HTTP `POST` para a sua `notification_url` com o payload abaixo:

```json theme={null}
{
  "event": "charge.paid",
  "timestamp": "2026-08-26T12:05:12.000Z",
  "data": {
    "id": "PAY9B1DEB4D3B7D4BAD9BDD2B",
    "status": "paid",
    "amount": 49.00,
    "fee": 0.99,
    "net": 48.01,
    "externalId": "ped_998811",
    "paid_at": "2026-08-26T12:05:12.000Z",
    "end_to_end_id": "E9274656202608261205abcdef",
    "customer": {
      "name": "Carlos Eduardo Silva",
      "document": "12345678909",
      "email": "carlos@email.com.br",
      "phone": "11987654321"
    },
    "metadata": {
      "order_id": "ped_998811",
      "utm_source": "google_ads"
    }
  }
}
```

## Boas Práticas ao Receber Webhooks

<Tip>
  Retorne sempre o status **HTTP 200 OK** de imediato para acusar o recebimento com sucesso.
</Tip>

* Caso seu endpoint retorne erro 5xx ou 4xx, o sistema da KavroPay tentará reenviar automaticamente com retentativas exponenciais.
* Trate o `externalId` ou `id` de forma idempotente para não liberar o produto duas vezes.

<CardGroup cols={2}>
  <Card title="Anterior: Consulta de Saldo" icon="arrow-left" horizontal href="/saldo-conta" />

  <Card title="Próximo: Idempotência & Rede" icon="arrow-right" horizontal href="/infraestrutura" />
</CardGroup>