Webhook de pagamento: boas práticas em 2026 pra não perder venda

90% dos bugs de venda em produção vêm de webhook mal implementado. Cliente pagou, gateway confirmou, mas você não liberou o produto porque o webhook falhou silenciosamente. Aqui os 8 padrões pra webhook nunca perder venda.

1. Sempre valide HMAC

Nunca confie no body do webhook sem verificar assinatura. Sem HMAC, qualquer um pode postar "venda paga" e você libera produto de graça:

import { createHmac, timingSafeEqual } from "crypto";

function verifyWebhook(rawBody, signatureHeader, secret) {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const provided = signatureHeader.replace("sha256=", "");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(provided));
}

2. Idempotência via ID do evento

Webhook pode chegar 2x se seu servidor demorar a responder 200. Guarda o event_id do webhook e ignora duplicado:

const exists = await db.webhookEvents.findUnique({ where: { id: event.id }});
if (exists) return res.status(200).send("already_processed");
// ... processa
await db.webhookEvents.create({ data: { id: event.id }});

3. Responda 200 rápido, processe assíncrono

Gateway espera resposta em 5s. Se você processa síncrono (envia email, libera acesso, atualiza CRM) pode timeout. Melhor: responde 200 imediato, enfileira job async pra processar.

4. Tratar retry corretamente

Se seu servidor cai, o gateway retenta. Aceite retry sem quebrar. Idempotência (item 2) resolve.

5. Verifique via API antes de creditar

Recebeu "PAID"? Confirma via API do gateway antes de liberar produto de valor alto. Custo: 100ms. Benefício: zero fraude.

6. Logging estruturado

Cada webhook que chega, loga JSON com event_id, status, timestamp, verificação HMAC ok/nok. Facilita debug 3 meses depois.

7. Dead-letter queue

Webhook falhou 5x seguidas? Move pra dead-letter e alerta engenharia. Não deixa reprocessar infinito.

8. Monitoramento

Alerta se webhook_success_rate cair abaixo de 99%. Alerta se tempo médio subir. Prometheus + Grafana ou Datadog.

Se você usa BravoPay, os itens 1, 3, 4 e 7 já vêm implementados no nosso lado. Você só precisa dos 2, 5, 6 e 8 no seu.