Webhooks que sobrevivem a novas tentativas

Webhooks são o momento em que um sistema de pagamentos passa a responsabilidade para o seu código. Eles chegam pela internet pública, às vezes duas vezes, às vezes atrasados. Projetar para isso é a diferença entre uma integração confiável e uma fila de suporte.

O que o FeitPay garante

• Entrega pelo menos uma vez. Cada evento é gravado em um outbox na mesma transação da mudança de estado e depois entregue com backoff exponencial e jitter. Após o número máximo de tentativas, as entregas que falharam ficam em uma lista de mensagens mortas (dead-letter) que você pode reenviar.
• Uma identidade estável. Cada evento carrega um event_id. As novas tentativas reutilizam esse ID.
• Uma assinatura verificável. O cabeçalho FeitPay-Signature contém um timestamp e um HMAC-SHA256 sobre timestamp + "." + raw_body, calculado com o segredo de assinatura do seu endpoint.

O que o seu endpoint deve fazer

import { verifyWebhook } from '@feitpay/webhooks';

// Rejects stale timestamps (300 s tolerance) and accepts the previous secret during rotation.
const event = await verifyWebhook({
  payload: rawBody, // the exact bytes received
  header: request.headers['feitpay-signature'],
  secrets: [process.env.FEITPAY_WEBHOOK_SECRET, process.env.FEITPAY_WEBHOOK_SECRET_PREVIOUS].filter(Boolean),
});

if (await alreadyProcessed(event.event_id)) return ok();

Três hábitos são os mais importantes:

1. Verifique contra o corpo bruto. Um JSON serializado de novo não vai corresponder à assinatura.
2. Deduplique pelo event_id. Trate um evento repetido como sucesso, não como erro.
3. Confirme antes de ações irreversíveis. Em entregas de alto valor, busque o pagamento na API e verifique o estado dele antes de enviar o pedido.

Rotação de segredos sem indisponibilidade

Quando você faz a rotação do segredo de um endpoint, as entregas são assinadas com o segredo novo e com o anterior durante uma curta janela de sobreposição, para que os verificadores possam fazer a troca sem perder eventos. Os segredos são exibidos uma única vez, criptografados em repouso e nunca registrados em logs.