Webhooks explicados: payloads assinados e retentativas
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:
- Segurança: Como você sabe que a requisição veio do remetente legítimo?
- Confiabilidade: E se seu endpoint estiver fora do ar ou lento?
- Duplicatas: Redes podem causar retentativas; você pode receber o mesmo evento várias vezes.
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 é:
- Provedor e consumidor compartilham uma chave secreta.
- O provedor cria o payload, calcula HMAC-SHA256(segredo, payload) e envia em um cabeçalho.
- 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
- Validação de timestamp: Inclua um timestamp no payload assinado e rejeite requisições antigas para prevenir ataques de replay.
- HTTPS: Sempre use HTTPS para endpoints de webhook.
- Rotação de segredo: Suporte múltiplos segredos ativos para permitir rotação sem downtime.
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:
- Retentativa 1: após 1 minuto
- Retentativa 2: após 5 minutos
- Retentativa 3: após 30 minutos
- Retentativa 4: após 2 horas
- Retentativa 5: após 24 horas
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:
- Responda rapidamente: Confirme o recebimento com um status 2xx antes de processar trabalho pesado. Use uma fila.
- Idempotência: Lide com eventos duplicados de forma elegante. Use o ID do evento para deduplicar.
- Monitore falhas: Registre falhas e configure alertas.
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:
- Armazene IDs de eventos processados em um banco de dados com uma restrição de unicidade.
- Antes de processar, verifique se o ID já existe; se sim, retorne 200 OK sem reprocessar.
- Para operações que alteram estado, use chaves de idempotência.
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.