Papel
Você registra uma URL pública (HTTPS) na plataforma para receber notificações POST com JSON e headerDigital-Signature. A documentação de origem referencia:
POST/webhook— registroGET/webhook— listagemDELETE/webhook/{webhook_id}— remoção
TODO: schema JSON de criação e campos — corpo de POST /webhook (URL, events[], secret?, active?, etc.) não está no documento fonte; alinhe com a API ou suporte.
Eventos (strings exatas)
event na inscrição | Quando dispara |
|---|---|
pix_cash_in | Cash-in atinge terminal relevante (PAID / FAILED). |
pix_cash_out | Cash-out confirmado ou falha terminal de liquidação. |
pix_cash_in_reversal | Refund-in confirmado ou falha. |
pix_cash_out_reversal | Cash-out previamente confirmado é revertido. |
Arquitetura do recebedor (recomendada)
- Rápido: responda 2xx em poucos segundos (recomendação: < 2–10 s na origem; trate a referência operacional de SLA como ponto de ajuste com o SRE).
- Assíncrono: valide a assinatura, faça enfileiramento e processe o negócio em worker interno.
- Idempotente: deduplique com chave apropriada (idempotência).
- IP allowlist (opcional):
TODOse a plataforma publicar blocos CIDR/egress; o documento não detalha.
Segurança básica
- Sempre validar a assinatura no corpo bruto.
- TLS obrigatório; certificados públicos corretos.
- Rotação de chave pública: obtenha via
GET /public-key(ver referência de API).
Entrega e retentativas
Falhas transitórias no seuPOST alimentam retentativas (fila com backoff, conforme a origem). Garanta que retentar o mesmo aviso não duplique efeito colateral (idempotência).
Outbox (cash-in e refund-in)
Atualizações que trafegam pelo outbox interno: a notificação fica alinhada ao commit do banco, com dispatcher reexecutando o HTTP. Variáveis típicas documentadas:PIX_STATUS_NOTIFICATION_WORKERS, PIX_STATUS_NOTIFICATION_POLL_SEC, PIX_STATUS_NOTIFICATION_MAX_ATTEMPTS (valores ajustam por ambiente).