Pular para o conteúdo

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 Ícone da StarpStarp recebe e monitora webhooks da Meta e de outras plataformas com esse padrão. Veja sistemas web ou fale com a gente.

  • Webhooks
  • Integrações
  • Backend
  • Idempotência
CompartilharWhatsAppLinkedIn

Escrito por

Roger C. Ribeiro

Fundador 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.