Por que chegam duplicados
- O sistema demorou para responder e o remetente considerou falha
- O sistema respondeu com erro, mesmo tendo processado parte da ação
- O remetente envia o mesmo evento mais de uma vez por desenho
Por que se perdem
- Endereço errado ou desatualizado no cadastro do webhook
- Bloqueio no servidor (firewall, proteção contra robôs)
- Sistema fora do ar além do período de novas tentativas do remetente
- Erro que impede salvar o aviso recebido
O padrão correto
| Etapa | O que fazer |
|---|---|
| Receber | Validar a assinatura, salvar o evento e responder sucesso imediatamente |
| Deduplicar | Ignorar eventos cujo ID já foi registrado (idempotência) |
| Processar | Executar a ação em segundo plano, em uma fila |
| Ordenar | Não deixar um evento antigo sobrescrever um estado mais recente |
| Conciliar | Consultar periodicamente a origem para recuperar eventos perdidos |
| Monitorar | Alertar quando há falhas ou nenhum evento por tempo anormal |
Leia também
Veja os casos práticos em pagamento aprovado, mas pedido não atualizado e mensagens ou cobranças duplicadas. Corrigimos o recebimento de webhooks no nosso serviço de manutenção de sistemas PHP e Laravel.