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

# Fundamentos de webhook

> Use webhooks como fonte principal de verdade para pagamentos, assinaturas e transferências assíncronas, com polling apenas como contingência.

Use webhooks para dirigir o estado de pagamentos, assinaturas e payouts. Use polling apenas para debug, recuperação ou reconciliação.

## Quando usar webhooks

* Mudanças de estado de pagamento em fluxos Pix, voucher e cartão
* Renovações, falhas, atualizações e cancelamento de assinaturas
* Progresso e liquidação de transferências Pix Out
* Atualização rápida de pedidos e payouts sem polling no front-end

## Padrões de entrega

### Assinaturas centrais

Use um endpoint estável quando quiser um pipeline único de ingestão para todos os eventos recorrentes.

### Callbacks por requisição

Defina `notify_url` em uma transação ou transferência específica quando apenas um fluxo precisar receber aquele callback.

## Exemplo de requisição com `notify_url`

```json theme={null}
{
  "external_ref": "order_1001",
  "amount": 1500,
  "currency": "BRL",
  "method": "pix",
  "notify_url": "https://shop.example/webhooks/pagou",
  "buyer": {
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "document": {
      "type": "CPF",
      "number": "12345678901"
    }
  },
  "products": [
    {
      "name": "Starter order",
      "price": 1500,
      "quantity": 1
    }
  ]
}
```

## Resposta mínima de ACK

```json theme={null}
{
  "received": true
}
```

## Erro comum de ingestão

Status `400`

```json theme={null}
{
  "error": "missing_event_id"
}
```

Como corrigir: valide o `id` de topo do webhook antes de enfileirar trabalho. Faça deduplicação por esse ID e depois processe de forma assíncrona.

## Fluxo recomendado de ingestão

1. Receba o `POST` HTTPS.
2. Valide o ID de topo do evento.
3. Responda `200 OK` rapidamente.
4. Persista ou enfileire o payload.
5. Reconcilie com `GET` se o worker cair ou se algum efeito colateral ficar incerto.

## Próximos passos

* [Visão geral de webhooks](/pt/webhooks/overview)
* [Eventos de pagamento](/pt/webhooks/payment-events)
* [Webhooks de assinatura](/pt/subscriptions/webhooks)
* [Eventos de transferência](/pt/webhooks/transfer-events)