Webhooks Explicados: Payloads Assinados e Estratégias de Retry
Você construiu uma API que envia webhooks para notificar serviços externos sobre eventos. Mas o que acontece quando o endpoint receptor está fora do ar? Ou quando um ator malicioso tenta forjar uma requisição de webhook? Sem as devidas proteções, seus webhooks podem se tornar uma fonte de inconsistência de dados e vulnerabilidades de segurança. Este artigo explica como implementar payloads assinados e mecanismos de retry para tornar seus webhooks confiáveis e seguros.
O Que São Webhooks e Por Que Precisam de Segurança?
Webhooks são callbacks HTTP definidos pelo usuário que são acionados por eventos específicos. Eles permitem comunicação em tempo real entre sistemas, como notificar um serviço de pagamento quando um pedido é feito. No entanto, como webhooks são endpoints publicamente acessíveis, eles são suscetíveis a spoofing e ataques de replay. Além disso, problemas de rede ou indisponibilidade do receptor podem causar eventos perdidos. Portanto, dois aspectos críticos devem ser tratados: autenticidade (via payloads assinados) e confiabilidade (via retries).
Payloads Assinados: Garantindo Autenticidade e Integridade
Um payload assinado permite ao receptor verificar que o webhook se originou de uma fonte confiável e que os dados não foram adulterados. Isso é tipicamente alcançado usando HMAC (Hash-based Message Authentication Code) com um segredo compartilhado.
Como Funciona a Assinatura HMAC
O remetente e o receptor compartilham uma chave secreta. Para cada requisição de webhook, o remetente calcula uma assinatura HMAC usando o segredo e o payload da requisição (frequentemente incluindo um timestamp para prevenir ataques de replay). A assinatura é enviada em um header, como X-Signature. O receptor recalcula a assinatura e a compara com a recebida. Se corresponderem, a requisição é autêntica.
Aqui está um exemplo em Python usando HMAC-SHA256:
import hmac
import hashlib
import time
secret = b'your_shared_secret'
payload = b'{"event":"order.created","id":123}'
timestamp = str(int(time.time())).encode()
message = timestamp + b'.' + payload
signature = hmac.new(secret, message, hashlib.sha256).hexdigest()
# Send headers: X-Signature: signature, X-Timestamp: timestamp
No lado do receptor, verifique a assinatura e confira o timestamp para garantir que a requisição é recente (por exemplo, dentro de 5 minutos). Isso previne ataques de replay.
Boas Práticas para Payloads Assinados
- Use um segredo forte: Gere um segredo aleatório de alta entropia e armazene-o com segurança.
- Inclua um timestamp: Rejeite requisições com timestamps fora de uma janela aceitável.
- Use comparação em tempo constante: Previna ataques de timing usando funções como
hmac.compare_digest. - Rotacione segredos periodicamente: Permita múltiplos segredos ativos durante a rotação.
Mecanismos de Retry: Garantindo Entrega Confiável
Mesmo com payloads assinados, falhas de rede ou erros do receptor podem fazer a entrega do webhook falhar. Uma estratégia de retry robusta garante que os eventos sejam eventualmente entregues sem sobrecarregar o receptor.
Projetando uma Política de Retry
Uma abordagem comum é o 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.
Exemplo de cronograma de retry:
| Tentativa | Atraso |
|---|---|
| 1 | Imediato |
| 2 | 1 minuto |
| 3 | 5 minutos |
| 4 | 30 minutos |
| 5 | 2 horas |
Após esgotar as tentativas, mova o evento para uma dead-letter queue para inspeção manual.
Idempotência: Lidando com Entregas Duplicadas
Como os retries podem causar entregas duplicadas, os receptores devem ser idempotentes. Inclua um ID de evento no payload e faça o receptor armazenar IDs processados para ignorar duplicatas. Alternativamente, projete operações para serem naturalmente idempotentes (por exemplo, usando PUT em vez de POST).
Implementando Webhooks: Um Guia Passo a Passo
- Defina eventos e estrutura do payload: Documente os eventos que seu sistema emite e o schema JSON para cada um.
- Gere um segredo: Crie um segredo único por endpoint de webhook e compartilhe-o com segurança.
- Assine cada requisição: Calcule HMAC sobre o payload e o timestamp, inclua nos headers.
- Implemente retries com backoff: Use um sistema de filas para agendar retries.
- Forneça uma forma de verificar assinaturas: Documente o processo de verificação para os receptores.
- Monitore e registre: Acompanhe tentativas de entrega e falhas para depuração.
Armadilhas Comuns e Como Evitá-las
- Ignorar TLS: Sempre use HTTPS para proteger payloads em trânsito.
- Não validar o timestamp: Permite ataques de replay.
- Retentar indefinidamente: Pode causar esgotamento de recursos; defina um máximo.
- Assumir entrega imediata: Projete para processamento assíncrono.
FAQ
O que é um payload de webhook assinado?
Um payload de webhook assinado inclui uma assinatura criptográfica (por exemplo, HMAC) que permite ao receptor verificar a autenticidade do remetente e a integridade dos dados.
Quantas vezes devo retentar um webhook com falha?
Tipicamente 3 a 5 retries com backoff exponencial. O número exato depende do seu SLA e da criticidade do evento.
Posso usar JWT em vez de HMAC para assinaturas de webhook?
Sim, JWT pode ser usado, mas HMAC é mais simples e mais comum para assinatura de webhooks. JWT adiciona overhead e é mais adequado para tokens de autenticação.
Pronto para testar seus payloads de webhook? Use nosso formatador JSON para validar e embelezar seus payloads JSON antes de enviar.