Webhooks Explicados: Payloads Assinados e Retentativas
Você acabou de integrar um provedor de pagamento ou um serviço de CI/CD e agora precisa receber eventos em tempo real. Webhooks são a forma padrão de enviar dados entre sistemas, mas muitas implementações falham em produção devido a falhas de segurança ou entrega não confiável. Este guia explica como proteger webhooks com payloads assinados e implementar mecanismos de retentativa robustos.
O que são Webhooks e por que são importantes
Um webhook é um callback HTTP: quando um evento ocorre em um sistema de origem (por exemplo, um novo pedido), ele envia uma requisição HTTP POST para uma URL que você fornece. Diferente do polling, webhooks são eficientes e quase em tempo real. No entanto, como são baseados em HTTP, você deve lidar explicitamente com segurança e confiabilidade.
Casos de uso comuns incluem notificações de pagamento, gatilhos de pipeline de CI/CD, notificações de chat e sincronização de dados entre aplicações SaaS.
Protegendo Webhooks com Payloads Assinados
Webhooks são endpoints publicamente acessíveis, então atacantes podem enviar requisições falsas. Para evitar isso, os provedores assinam cada payload com uma chave secreta. O receptor verifica a assinatura para garantir autenticidade e integridade.
Como funcionam as assinaturas HMAC
O método mais comum é o HMAC-SHA256. O provedor calcula um hash do corpo da requisição usando um segredo compartilhado e o inclui em um cabeçalho (por exemplo, X-Signature). O receptor recalcula o hash e compara.
// Exemplo em Node.js: gerando uma assinatura
const crypto = require('crypto');
const secret = 'your_webhook_secret';
const payload = JSON.stringify({ event: 'order.created', id: 123 });
const signature = crypto.createHmac('sha256', secret).update(payload).digest('hex');
// Envie a assinatura no cabeçalho: X-Signature: sha256=...
Verificando assinaturas no receptor
Sempre use uma comparação de tempo constante para evitar ataques de temporização. Em Node.js, use crypto.timingSafeEqual.
// Exemplo de middleware Express.js
const crypto = require('crypto');
function verifySignature(req, res, next) {
const signature = req.headers['x-signature'];
const payload = JSON.stringify(req.body); // corpo bruto necessário
const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
const trusted = Buffer.from(`sha256=${expected}`, 'utf8');
const received = Buffer.from(signature, 'utf8');
if (trusted.length !== received.length || !crypto.timingSafeEqual(trusted, received)) {
return res.status(401).send('Invalid signature');
}
next();
}
Importante: Use o corpo bruto da requisição para verificação, não o JSON analisado, para evitar discrepâncias.
Medidas de segurança adicionais
- Validação de timestamp: Inclua um timestamp na assinatura e rejeite requisições mais antigas que alguns minutos para prevenir ataques de replay.
- Somente HTTPS: Sempre use endpoints HTTPS para proteger dados em trânsito.
- Lista de permissões de IP: Se o provedor publica intervalos de IP, restrinja requisições recebidas a esses IPs.
Implementando Retentativas Confiáveis
Webhooks podem falhar devido a problemas de rede, indisponibilidade do servidor ou bugs. Provedores normalmente tentam novamente entregas falhas com backoff exponencial. Como receptor, você deve ser idempotente e lidar com eventos duplicados.
Projetando para idempotência
Cada evento de webhook deve ter um ID único. Armazene IDs processados para ignorar duplicatas. Use um banco de dados com restrição de unicidade ou um cache como Redis.
// Pseudocódigo para processamento idempotente
if (await redis.exists(`webhook:${event.id}`)) {
return res.status(200).send('Already processed');
}
await processEvent(event);
await redis.set(`webhook:${event.id}`, '1', 'EX', 86400); // TTL de 24h
Estratégias de retentativa
Provedores geralmente tentam novamente com atrasos crescentes (por exemplo, 1s, 5s, 30s, 5m, 1h). Garanta que seu endpoint responda rapidamente (dentro de 5 segundos) para evitar timeouts. Se o processamento demorar mais, confirme o recebimento e processe de forma assíncrona.
Aqui está uma comparação de padrões comuns de retentativa:
| Padrão | Prós | Contras |
|---|---|---|
| Intervalo fixo | Simples | Pode sobrecarregar um servidor em recuperação |
| Backoff exponencial | Reduz a carga durante indisponibilidades | Entrega atrasada para erros transitórios |
| Backoff exponencial com jitter | Previne o efeito manada | Um pouco mais complexo |
Monitoramento e filas de mensagens mortas
Registre todas as tentativas e falhas de webhook. Após um número máximo de retentativas, mova eventos para uma fila de mensagens mortas (DLQ) para inspeção manual. Alerte sobre altas taxas de falha.
Juntando tudo: uma implementação passo a passo
- Configure um endpoint HTTPS que aceite requisições POST e leia o corpo bruto.
- Verifique a assinatura usando o segredo compartilhado e comparação de tempo constante.
- Verifique o timestamp para prevenir ataques de replay (se fornecido).
- Garanta a idempotência verificando o ID do evento em um cache ou banco de dados.
- Processe o evento de forma assíncrona se puder demorar; responda com 200 OK imediatamente.
- Implemente lógica de retentativa no lado do remetente com backoff exponencial e jitter.
- Monitore e alerte sobre falhas e use uma DLQ para erros persistentes.
Perguntas Frequentes
O que é um payload de webhook assinado?
Um payload assinado inclui uma assinatura criptográfica (geralmente HMAC) que permite ao receptor verificar que a requisição veio de uma fonte confiável e não foi adulterada.
Como lidar com eventos de webhook duplicados?
Use o ID único do evento fornecido no payload para rastrear eventos processados. Armazene os IDs em um banco de dados ou cache com TTL para ignorar duplicatas.
O que meu endpoint de webhook deve retornar?
Retorne um código de status 2xx (por exemplo, 200 OK) rapidamente para confirmar o recebimento. Se o processamento falhar, retorne um 5xx para acionar uma retentativa, mas apenas para erros transitórios.
Ao testar payloads de webhook, você pode precisar inspecionar estruturas JSON. Use o JSON Formatter para validar e formatar payloads de webhook para facilitar a depuração.