Todo webhook de pagamento precisa de três garantias: autenticidade (a requisição realmente veio de nós), entrega at-least-once (sem eventos silenciosamente perdidos) e idempotência (re-entregas não duplicam cobranças no seu BD).
Autenticidade: todo webhook Baynoy carrega um header X-Baynoy-Signature — sha256(timestamp + '.' + body) com o secret do seu endpoint. Rejeite se o timestamp for mais antigo que 5 minutos (defesa replay) ou a assinatura não bater em comparação constant-time. Seguimos o formato exato da Stripe, então o middleware de verificação Stripe existente encaixa sem mudanças.
At-least-once: re-tentamos com backoff exponencial a 1m, 5m, 30m, 2h, 12h, 24h — limitado a seis tentativas. Cada tentativa escreve uma linha em baynoy_webhook_deliveries com o status de resposta. O botão replay-from-UI no dashboard bate no mesmo pipeline de delivery; sem caminho especial.
Idempotência: todo evento carrega um event.id (UUIDv7 — ordenável, monotônicamente crescente). Persista no primeiro recebimento e rejeite duplicatas no nível BD com um unique constraint. Vamos re-entregar. O constraint é sua rede de segurança.
Três linhas de middleware e você tem um handler de webhook que sobrevive a um outage de 6 horas sem perder uma única notificação de pagamento.