Webhooks explicados: payloads assinados e retentativas

Backend2026-11-15TryQuickToolBox

Por que os webhooks quebram em produção

Você criou um endpoint de webhook, testou localmente e tudo funcionou. Então a produção chega: um provedor envia um evento duplicado, seu endpoint expira ou um atacante falsifica uma requisição. De repente, sua integração está instável e insegura.

Webhooks são simples em conceito — callbacks HTTP acionados por eventos — mas implementações de nível de produção exigem cuidado com segurança e confiabilidade. Este guia aborda dois aspectos críticos: payloads assinados para verificar autenticidade e estratégias de retentativa para lidar com falhas.

O que são webhooks?

Um webhook é um callback HTTP definido pelo usuário. Quando um evento ocorre em um sistema de origem (por exemplo, um pagamento é aprovado), ele envia uma requisição HTTP POST para uma URL que você fornece, contendo dados sobre o evento. Esse modelo de push é mais eficiente que o polling.

Mas webhooks introduzem desafios:

Vamos abordar a segurança primeiro.

Protegendo webhooks com payloads assinados

Payloads assinados usam um segredo compartilhado para criar uma assinatura criptográfica do corpo da requisição. O remetente inclui essa assinatura em um cabeçalho (por exemplo, X-Signature). Seu endpoint recalcula a assinatura e compara. Se corresponderem, a requisição é autêntica.

Como funciona a assinatura HMAC

A maioria dos provedores usa HMAC-SHA256. A assinatura é calculada sobre o corpo bruto da requisição usando o segredo compartilhado. O fluxo é:

  1. Provedor e consumidor compartilham uma chave secreta.
  2. O provedor cria o payload, calcula HMAC-SHA256(segredo, payload) e envia em um cabeçalho.
  3. O consumidor recebe a requisição, lê o corpo bruto, calcula o mesmo HMAC e compara.

Importante: Use o corpo bruto exatamente como recebido — analisar e reserializar JSON pode alterar os bytes e quebrar a assinatura.

Implementando a verificação de assinatura

Aqui está um exemplo em Node.js usando Express:

const crypto = require('crypto');
const express = require('express');
const app = express();

// Use raw body parser for webhook routes
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-signature'];
  const secret = process.env.WEBHOOK_SECRET;
  
  const expected = crypto
    .createHmac('sha256', secret)
    .update(req.body)
    .digest('hex');
  
  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process the event
  const event = JSON.parse(req.body);
  // ... handle event
  
  res.status(200).send('OK');
});

Sempre use uma comparação de tempo constante como crypto.timingSafeEqual para prevenir ataques de temporização.

Outras considerações de segurança

Implementando retentativas confiáveis

Mesmo com um endpoint seguro, problemas de rede ou falhas temporárias podem causar falha na entrega do webhook. Um mecanismo de retentativa robusto garante que eventos não sejam perdidos.

Estratégia de retentativa do lado do remetente

Se você está construindo um remetente de webhook, implemente backoff exponencial com jitter. Por exemplo:

Adicione jitter aleatório para evitar problemas de manada. Pare após um número máximo de tentativas e alerte.

Melhores práticas do lado do receptor

Como consumidor de webhook, você não pode controlar a política de retentativa do remetente, mas pode tornar seu endpoint resiliente:

Lidando com duplicatas usando idempotência

Provedores de webhook frequentemente retentam em timeouts, então você pode receber o mesmo evento várias vezes. Torne seu processamento idempotente:

Exemplo usando um índice único de banco de dados:

async function handleEvent(event) {
  try {
    await db.query('INSERT INTO processed_events (id) VALUES ($1)', [event.id]);
  } catch (err) {
    if (err.code === '23505') { // unique violation
      return; // already processed
    }
    throw err;
  }
  // process event
}

Comparação: abordagens de segurança para webhooks

Abordagem Prós Contras
Assinatura HMAC Integridade forte, amplamente suportada Requer gerenciamento de segredos
Basic Auth Simples Menos segura, credenciais no cabeçalho
Lista de IPs permitidos Fácil de implementar IPs podem mudar, não é robusto

Assinaturas HMAC são o padrão de facto para segurança de webhooks.

Testando webhooks localmente

Ferramentas como ngrok ou localtunnel expõem seu servidor local à internet para testes. Sempre teste a verificação de assinatura e a lógica de retentativa com falhas simuladas.

Ao inspecionar payloads JSON de webhooks, formatá-los pode ajudar na depuração. Experimente nosso Formatador JSON para imprimir e validar payloads de webhook.

FAQ

Como verifico a assinatura de um webhook?

Calcule um HMAC do corpo bruto da requisição usando o segredo compartilhado e compare-o com o cabeçalho de assinatura usando uma função de comparação de tempo constante.

O que devo fazer se meu endpoint de webhook estiver fora do ar?

A maioria dos provedores retenta com backoff exponencial. Garanta que seu endpoint retorne um 2xx rapidamente e processe de forma assíncrona para minimizar o impacto do downtime.

Posso usar webhooks sem assinaturas?

É arriscado. Sem assinaturas, atacantes podem falsificar requisições. Sempre use payloads assinados ou pelo menos autenticação básica sobre HTTPS.

Conclusão

Webhooks são poderosos, mas exigem atenção à segurança e confiabilidade. Implemente verificação de assinatura HMAC para garantir autenticidade e projete seu sistema para lidar com retentativas e duplicatas de forma elegante. Com essas práticas, suas integrações de webhook serão robustas e prontas para produção.