Problema real e contexto
Eventos de pagamento e comunicação precisavam ser processados com confiabilidade e sem perda de contexto.
O foco foi garantir consistência operacional mesmo com falhas transitórias de provedores.
Decisões técnicas
-
Validação de assinatura e autenticação de webhooks.
-
Processamento assíncrono com retries exponenciais.
-
DLQ para eventos inválidos ou com falha recorrente.
-
Ledger de auditoria para rastrear estado de cada evento.
Tip: Nunca execute lógica pesada na recepção síncrona do webhook.
Checklist final
-
Validar assinatura antes de persistir evento.
-
Registrar idempotency key por provider event id.
-
Definir política clara de retry e dead-letter.
-
Criar dashboards de sucesso, atraso e falha.
Erros comuns
-
Ignorar ordem de entrega de webhooks.
-
Não tratar eventos duplicados como cenário normal.
-
Falta de trilha de auditoria para reconciliação financeira.