Webhooks Explicados: Payloads Assinados e Retentativas Confiáveis

Você acabou de integrar um gateway de pagamento de terceiros ou um serviço de CI/CD, e agora precisa de notificações em tempo real. Webhooks são a resposta — mas sem segurança e confiabilidade adequadas, podem se tornar uma fonte de frustração. Atacantes podem falsificar requisições, e falhas de rede podem causar perda de eventos. Neste guia, vamos abordar como proteger webhooks com payloads assinados e implementar mecanismos robustos de retentativa.

O Que São Webhooks?

Webhooks são callbacks HTTP definidos pelo usuário, acionados por eventos específicos. Quando um evento ocorre (por exemplo, um pagamento é bem-sucedido), o serviço de origem envia uma requisição HTTP POST para uma URL que você fornece, contendo os dados do evento. Esse modelo de push é mais eficiente que o polling e permite reações em tempo real.

No entanto, webhooks introduzem dois desafios: autenticidade (garantir que a requisição vem do remetente esperado) e confiabilidade (garantir que você não perca eventos).

Protegendo Webhooks com Payloads Assinados

Um payload assinado usa um segredo compartilhado entre remetente e receptor para criar uma assinatura criptográfica. O remetente inclui essa assinatura em um cabeçalho, e o receptor a verifica para confirmar a integridade e a origem do payload.

Como Funciona a Assinatura HMAC

HMAC (Hash-based Message Authentication Code) é a abordagem padrão. O remetente calcula um HMAC sobre o corpo da requisição usando o segredo compartilhado e o inclui em um cabeçalho como X-Signature. O receptor recalcula o HMAC e compara.

// Exemplo: Gerando uma assinatura em Node.js
const crypto = require('crypto');

function generateSignature(payload, secret) {
  return crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
}

// No lado receptor, verifique:
function verifySignature(payload, secret, receivedSignature) {
  const expected = generateSignature(payload, secret);
  // Use comparação timing-safe para prevenir ataques de temporização
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(receivedSignature, 'hex')
  );
}

Pontos-chave:

• Sempre use um segredo forte e exclusivo por endpoint de webhook.
• Compare assinaturas usando uma função timing-safe para evitar vazamento de informações.
• Inclua um timestamp na assinatura para prevenir ataques de replay (por exemplo, assine timestamp + payload).

Medidas Adicionais de Segurança

• HTTPS: Sempre use HTTPS para criptografar dados em trânsito.
• Allowlist de IP: Se o provedor publica faixas de IP, restrinja requisições recebidas a esses IPs.
• Limites de tamanho de payload: Rejeite payloads excessivamente grandes para mitigar DoS.

Implementando Retentativas Confiáveis

Redes não são confiáveis. Um webhook pode falhar devido a timeouts, erros de servidor ou indisponibilidades temporárias. Uma estratégia robusta de retentativa garante a entrega eventual sem sobrecarregar seu sistema ou o remetente.

Boas Práticas de Retentativa

1. Backoff exponencial: Aumente o intervalo entre retentativas (por exemplo, 1s, 2s, 4s, 8s...).
2. Limite máximo de retentativas: Defina um teto para o número de tentativas (por exemplo, 5) para evitar loops infinitos.
3. Fila de mensagens mortas: Após esgotar as retentativas, armazene os eventos com falha para inspeção manual.
4. Idempotência: Garanta que processar o mesmo evento várias vezes não cause efeitos colaterais duplicados.

Idempotência na Prática

Inclua um ID de evento exclusivo no payload. No lado receptor, rastreie IDs processados (em um banco de dados ou cache) e ignore duplicatas. Por exemplo:

// Pseudocódigo para processamento idempotente
if (eventStore.exists(event.id)) {
  return 200; // Já processado
}
// Processa o evento...
eventStore.save(event.id);

Tratando Falhas com Elegância

Responda rapidamente com um status 2xx para confirmar o recebimento. Se o processamento demorar, enfileire o evento e processe de forma assíncrona. Retorne 5xx apenas para erros transitórios que justifiquem uma retentativa; para erros permanentes (por exemplo, payload inválido), retorne 4xx para evitar retentativas inúteis.

Comparação: Push vs. Poll

Testando Sua Implementação de Webhook

Use ferramentas como ngrok para expor seu servidor local e simular entregas de webhook. Verifique a validação de assinatura e o comportamento de retentativa ao falhar requisições intencionalmente.

FAQ

O que é um payload de webhook assinado?

Um payload assinado inclui uma assinatura criptográfica (frequentemente HMAC) que permite ao receptor verificar a autenticidade e integridade da requisição usando um segredo compartilhado.

Quantas vezes devo tentar novamente um webhook com falha?

Não há um número universal, mas 3–5 retentativas com backoff exponencial são comuns. Depois disso, registre a falha para revisão manual.

Posso usar webhooks sem HTTPS?

Tecnicamente sim, mas é altamente inseguro. Sempre use HTTPS para prevenir interceptação e ataques man-in-the-middle.

Pronto para inspecionar payloads de webhook? Use nosso formatador JSON para formatar e validar payloads JSON rapidamente.