Webhooks confiáveis: idempotência, retentativas e ordem dos eventos

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

O WOCOM Hub recebe e monitora webhooks da Meta e de outras plataformas com esse padrão. Veja sistemas web ou fale com a gente.