Fundamentos de webhook

​

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

​

Callbacks por requisição

​

Exemplo de requisição com notify_url

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

{
  "received": true
}

​

Erro comum de ingestão

{
  "error": "missing_event_id"
}

​

Assinatura HMAC

​

Fluxo recomendado de ingestão

1. Receba o POST HTTPS.
2. Quando o webhook tem Token de Segurança, verifique a assinatura. Veja Verificando a assinatura HMAC.
3. Valide o ID de topo do evento.
4. Responda 200 OK rapidamente.
5. Persista ou enfileire o payload.
6. Reconcilie com GET se o worker cair ou se algum efeito colateral ficar incerto.

​

Próximos passos

• Verificando a assinatura HMAC
• Visão geral de webhooks
• Eventos de pagamento
• Webhooks de assinatura
• Eventos de transferência