Pular para o conteúdo principal
Use webhooks para dirigir o estado de pagamentos e payouts. Use polling apenas para debug, recuperação ou reconciliação.

​
Quando usar webhooks

  • Mudanças de estado de pagamento em fluxos Pix e cartão
  • 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

{
  "external_ref": "order_1001",
  "amount": 1500,
  "currency": "BRL",
  "method": "pix",
  "notify_url": "https://merchant.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

{
  "received": true
}

​
Erro comum de ingestão

Status 400 
{
  "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