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

# Webhooks

> Receba eventos de pagamentos e saques na URL de cada operação.

Não existe cadastro global de webhook. A URL entra em `notification_url` ao criar PIX, link ou saque. Os eventos daquele registro vão somente para essa URL.

<Note>
  A `notification_url` é obrigatória no PIX avulso e opcional no link de pagamento e no saque.
</Note>

## Requisitos da URL

Use HTTPS público. IPs privados, localhost e URL com usuário/senha são recusados (`422`). Sem URL, nenhum POST é enviado.

## Headers

| Header                 | Descrição                                        |
| ---------------------- | ------------------------------------------------ |
| `X-AgitaPay-Event`     | Nome do evento                                   |
| `X-AgitaPay-Event-Id`  | ID único da entrega                              |
| `X-AgitaPay-Signature` | HMAC `sha256=...` quando houver `webhook_secret` |

O corpo inclui `store` (`id`, `name`). Quando existe `webhook_secret`, calcule o HMAC-SHA256 do JSON recebido e compare com a assinatura após `sha256=`.

## Eventos

| Pagamento         | Saque                  |
| ----------------- | ---------------------- |
| `payment.created` | `withdrawal.requested` |
| `payment.paid`    | `withdrawal.sent`      |
| `payment.expired` | `withdrawal.failed`    |
| `payment.failed`  |                        |

Entregas com falha são reenviadas com backoff. Use `X-AgitaPay-Event-Id` para deduplicar.

<Warning>
  O POST é um aviso. Responda `2xx` rápido e confirme o estado com `GET /payments/{id}` ou `GET /withdrawals/{id}` antes de liberar produto ou marcar saque.
</Warning>