Como integrar webhook de pagamento sem duplicar pedidos ou ativações?

Webhook de pagamento precisa ser pensado como evento assíncrono e repetível. A documentação da Stripe destaca explicitamente que o mesmo evento pode ser entregue mais de uma vez, e por isso o endpoint deve tratar duplicidade como comportamento normal. Em outras palavras, integração de webhook confiável precisa ser idempotente.

Na prática, isso significa validar a assinatura do provedor, registrar o identificador do evento recebido e impedir que o mesmo processamento gere duas ativações, dois pedidos ou duas mudanças de status. Em alguns cenários, também faz sentido considerar a combinação entre o tipo do evento e o objeto de negócio afetado, porque provedores podem emitir eventos diferentes sobre o mesmo pagamento.

Outro cuidado importante é não depender apenas do retorno do usuário para o site depois do pagamento. O redirecionamento pode falhar, o navegador pode ser fechado e a confirmação bancária pode chegar depois. O webhook existe justamente para representar a fonte assíncrona mais confiável do processo.

Quando o fluxo está bem desenhado, o sistema confirma, reconcilia e registra o pagamento com segurança, mesmo que a notificação chegue atrasada, duplicada ou fora da ordem ideal.