Receber webhook de pagamento Pix

Resposta rápida: Publique um endpoint HTTPS que aceite POST do PSP, registre a URL conforme a API/painel de webhooks, responda 200 rápido e processe com idempotência (endToEndId); use polling da cob como fallback.

Pré-requisitos

• Consultar cobrança como fallback
• URL pública HTTPS ({{WEBHOOK_URL}})
• Referência webhooks

Passo a passo

1. Implemente um receptor POST (stubs em snippets/node/webhook-receiver.mjs e snippets/python/webhook_receiver.py).
2. Exponha com TLS (reverse proxy / cloud).
3. Configure o webhook no PSP (endpoints de webhook do OpenAPI BACEN e/ou painel Modobank — confirme o caminho oficial).
4. Valide autenticidade (IP allowlist, assinatura ou mútua autenticação — conforme orientação Modobank; o stub só loga o body).
5. Idempotência: ignore reentregas do mesmo endToEndId.
6. Atualize o pedido interno e, se necessário, confirme com GET cob.

Código

Fontes:

• snippets/node/webhook-receiver.mjs
• snippets/python/webhook_receiver.py

Node.js (stub local)

// source: snippets/node/webhook-receiver.mjs
// run: node snippets/node/webhook-receiver.mjs

Python (stub local)

# source: snippets/python/webhook_receiver.py

Se der errado

Sintoma	Causa	Ação
PSP não entrega	URL inacessível / TLS	Testar com curl externo
Duplicatas	Sem idempotência	Chave por endToEndId
Payload estranho	Versão API	Log raw + OpenAPI

Checklist

• HTTPS válido
• 200 rápido (< poucos segundos)
• Idempotência testada
• Fallback GET cob

Próximo passo

Happy path v1 completo. Expansões (cobv, lotes) ficam para o próximo ciclo do pack.

FAQ

P: Webhook substitui GET cob?

R: Complementa. Em dúvida, reconcilie com GET.