Webhooks confiáveis: idempotência, retentativas e ordem dos eventos
Webhooks chegam duplicados, fora de ordem ou nem chegam — e o pedido fica "pendente" para sempre. Veja como receber webhooks de forma confiável.
Por Roger C. Ribeiro, fundador da Wecodex3 min de leitura
Webhooks chegam duplicados, fora de ordem ou nem chegam — e o pedido fica "pendente" para sempre. Veja como receber webhooks de forma confiável.
Gateways de pagamento, WhatsApp, marketplaces e ERPs avisam seu sistema sobre eventos por webhooks: uma requisição HTTP enviada quando algo acontece. Parece simples, mas é uma das fontes mais comuns de inconsistência em sistemas.
O que pode dar errado
- Duplicados: o parceiro reenvia se não recebeu confirmação a tempo.
- Fora de ordem: o evento "pago" chega antes do "criado".
- Perdidos: seu servidor estava fora no momento.
- Falsos: alguém envia um "pagamento aprovado" forjado.
Receba rápido, processe depois
Valide, grave o evento e responda 200 imediatamente. O processamento acontece numa fila (Filas e jobs em background: tirando tarefas pesadas da requisição). Se o seu código demorar, o parceiro reenvia — e o problema de duplicados piora.
Idempotência
Guarde o identificador de cada evento. Se chegar de novo, ignore. É a mesma lógica de Idempotência: como evitar cobrança duplicada e pedidos repetidos.
Ordem e estado
Não confie na ordem de chegada. Ao processar, consulte o estado atual no parceiro quando necessário, ou compare datas antes de atualizar.
Autenticidade
Verifique a assinatura enviada pelo parceiro antes de aceitar o evento — como em Assinatura HMAC em webhooks: como saber que a mensagem é legítima.
Reconciliação
Mesmo com tudo certo, alguns eventos se perdem. Uma rotina periódica que compara o seu estado com o do parceiro corrige o que escapou.
Monitoramento
Alertas para webhooks falhando ou parados há muito tempo (Observabilidade para quem não é SRE: métricas, logs e traces).
A 
- Webhooks
- Integrações
- Backend
- Idempotência
Escrito por
Roger C. RibeiroFundador da Wecodex. Escreve sobre engenharia de software, performance, APIs, segurança e IA aplicada a empresas.
Serviços relacionados
Resolver de vez, com quem faz isso todo dia
Precisa de uma API ou integração que não caia quando o negócio crescer?
Este artigo mostra o caminho. A implementação sob medida, o detalhe que muda o resultado no seu caso, é o trabalho da Wecodex, empresa de engenharia do grupo Wocom.
Continue lendo
Tudo sobre Backend & APIs- Ler artigo
Backend & APIs3 min
Idempotência: como evitar cobrança duplicada e pedidos repetidos
O cliente clicou duas vezes em "pagar" e foi cobrado duas vezes. Idempotência é a técnica que impede isso — e todo sistema com pagamentos precisa dela.
- Ler artigo
Segurança3 min
Assinatura HMAC em webhooks: como saber que a mensagem é legítima
Qualquer um pode enviar um "pagamento aprovado" falso para a URL do seu webhook. A assinatura HMAC prova que a mensagem veio mesmo do parceiro.
- Ler artigo
Backend & APIs3 min
Filas e jobs em background: tirando tarefas pesadas da requisição
O usuário clica em "gerar relatório" e espera 40 segundos com a tela travada. Veja como tirar tarefas pesadas da requisição com filas e jobs.