Webhooks Explicados: Payloads Assinados e Retentativas Confiáveis
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
- Use HTTPS para proteger o payload em trânsito.
- Armazene segredos com segurança (por exemplo, variáveis de ambiente, gerenciadores de segredos).
- Valide o timestamp e rejeite requisições obsoletas.
- Registre falhas de verificação para monitoramento.
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
| Aspecto | Polling | Webhooks |
|---|---|---|
| Latência | Alta (baseada em intervalo) | Baixa (quase em tempo real) |
| Carga do Servidor | Alta (requisições frequentes) | Baixa (orientada a eventos) |
| Complexidade | Simples de implementar | Requer verificação de assinatura e retentativas |
| Confiabilidade | Depende da frequência de polling | Depende do mecanismo de retentativa |
Passo a Passo: Construindo um Receptor de Webhook Seguro
- Configure um endpoint que aceite requisições POST via HTTPS.
- Verifique a assinatura usando o segredo compartilhado e rejeite requisições inválidas com 401.
- Verifique o timestamp para prevenir ataques de replay.
- Responda imediatamente com 200 OK após a validação básica e depois processe de forma assíncrona.
- Implemente idempotência usando IDs de evento para evitar processamento duplicado.
- 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.