Webhooks Explicados: Payloads Assinados e Retentativas Confiáveis

Backend2026-11-17TryQuickToolBox

Você acabou de integrar um serviço de terceiros que envia webhooks para o seu endpoint. Tudo funciona nos testes, mas em produção você percebe eventos perdidos, entregas duplicadas e até requisições forjadas. Webhooks são simples em conceito, mas complicados de acertar. Este artigo explica como proteger webhooks com payloads assinados e implementar lógica de retentativa confiável para que suas integrações sejam robustas e confiáveis.

O que são Webhooks e por que são importantes

Webhooks são callbacks HTTP definidos pelo usuário, acionados por eventos. Em vez de consultar uma API em busca de mudanças, você registra uma URL e o serviço envia uma requisição POST com os dados do evento sempre que algo acontece. Esse modelo push reduz a latência e a carga do servidor, tornando-o ideal para integrações em tempo real, como notificações de pagamento, gatilhos de CI/CD e mensagens de chat.

No entanto, webhooks introduzem desafios: verificar a autenticidade, lidar com falhas e garantir o processamento exatamente uma vez. Vamos abordar esses pontos um a um.

Protegendo Webhooks com Payloads Assinados

Sem verificação, qualquer pessoa pode enviar requisições falsas para o seu endpoint de webhook. Payloads assinados resolvem isso incluindo uma assinatura criptográfica nos cabeçalhos da requisição, gerada usando um segredo compartilhado. Você verifica a assinatura para confirmar que a requisição veio do remetente esperado e não foi adulterada.

Como funcionam as assinaturas HMAC

A maioria dos serviços usa HMAC (Hash-based Message Authentication Code) com SHA-256. O remetente calcula um hash do corpo da requisição (e às vezes de um timestamp) usando o segredo e o inclui em um cabeçalho como X-Signature. Você recalcula o hash do seu lado e compara.

Aqui está um fluxo típico de verificação em Node.js:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Sempre use uma comparação segura em relação ao tempo para evitar ataques de temporização. Além disso, inclua um timestamp nos dados assinados e rejeite requisições mais antigas que alguns minutos para evitar ataques de replay.

Melhores práticas para verificação de assinatura

Implementando Retentativas Confiáveis

Redes falham, servidores reiniciam e endpoints expiram. Um sistema de webhook robusto deve retentar entregas falhas. Mas retentativas podem causar duplicatas, então você precisa de idempotência.

Estratégias de Retentativa

A maioria dos provedores usa backoff exponencial com jitter. Por exemplo, retentar após 1 minuto, depois 5 minutos, depois 30 minutos, até um número máximo de tentativas (por exemplo, 5). Inclua um ID de evento único no payload para que o receptor possa deduplicar.

No lado do receptor, responda rapidamente com um status 2xx para confirmar o recebimento e depois processe de forma assíncrona. Se o processamento falhar, você não pode contar com o remetente para retentar indefinidamente — implemente sua própria fila de mensagens mortas ou alertas.

Chaves de Idempotência

Para lidar com entregas duplicadas, use uma chave de idempotência (frequentemente o ID do evento) e armazene os IDs processados por um período razoável. Antes de processar, verifique se o ID já foi visto; se sim, retorne sucesso sem reprocessar.

// Exemplo: verificação de idempotência no Express
app.post('/webhook', async (req, res) => {
  const eventId = req.body.id;
  if (await db.seenEvents.has(eventId)) {
    return res.status(200).send('Já processado');
  }
  await db.seenEvents.add(eventId);
  // processar evento de forma assíncrona
  res.status(200).send('OK');
});

Comparação: Polling vs Webhooks

AspectoPollingWebhooks
LatênciaAlta (baseada em intervalo)Baixa (quase em tempo real)
Carga do ServidorAlta (requisições frequentes)Baixa (orientada a eventos)
ComplexidadeSimples de implementarRequer verificação de assinatura e retentativas
ConfiabilidadeDepende da frequência de pollingDepende do mecanismo de retentativa

Passo a Passo: Construindo um Receptor de Webhook Seguro

  1. Configure um endpoint que aceite requisições POST via HTTPS.
  2. Verifique a assinatura usando o segredo compartilhado e rejeite requisições inválidas com 401.
  3. Verifique o timestamp para prevenir ataques de replay.
  4. Responda imediatamente com 200 OK após a validação básica e depois processe de forma assíncrona.
  5. Implemente idempotência usando IDs de evento para evitar processamento duplicado.
  6. Registre e monitore falhas e retentativas.

Perguntas Frequentes

O que é um payload de webhook assinado?

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

Quantas vezes devo retentar um webhook falho?

A prática comum é de 3 a 5 retentativas com backoff exponencial. Depois disso, mova o evento para uma fila de mensagens mortas para inspeção manual.

Posso usar webhooks sem HTTPS?

Não, HTTPS é essencial para proteger o payload e a assinatura contra interceptação e adulteração. Sempre use TLS.

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