Webhooks Explicados: Payloads Assinados e Retentativas para Integrações Confiáveis
Você acabou de criar um endpoint para receber webhooks de um provedor de pagamentos. O primeiro teste funciona bem, mas em produção você percebe eventos ausentes, cobranças duplicadas e nenhuma maneira de saber se uma requisição é genuína. Webhooks são simples em conceito, mas complicados de acertar. Este guia explica como proteger webhooks com payloads assinados e implementar uma lógica de retentativa robusta para que suas integrações não falhem silenciosamente.
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 sua aplicação consultar uma API em busca de mudanças (polling), o serviço envia dados para o seu endpoint quando algo acontece. Isso torna as integrações eficientes e quase em tempo real.
Casos de uso comuns incluem notificações de pagamento (ex.: Stripe), gatilhos de CI/CD (ex.: GitHub) e plataformas de mensagens (ex.: Slack). Mas com esse modelo de push, você perde o controle sobre quando as requisições chegam. É por isso que você precisa lidar explicitamente com segurança e confiabilidade.
O problema de segurança: Webhooks não assinados são perigosos
Um webhook não assinado é apenas um POST HTTP para uma URL pública. Qualquer pessoa pode enviar uma requisição que pareça ter vindo do seu provedor de pagamentos. Sem verificação, atacantes podem forjar eventos, levando a pedidos fraudulentos, vazamento de dados ou ações não autorizadas.
A solução é assinar o payload. O remetente calcula uma assinatura criptográfica sobre o corpo da requisição usando um segredo compartilhado e a inclui em um cabeçalho. Seu endpoint recalcula a assinatura e compara. Se forem iguais, você sabe que a requisição é autêntica e não foi adulterada.
Como assinar payloads de webhook com HMAC
HMAC (Hash-based Message Authentication Code) é o padrão para assinatura de webhooks. Ele usa uma chave secreta e uma função de hash (como SHA-256) para produzir uma assinatura única para o payload e o segredo.
Veja como um remetente pode assinar um payload em Python:
import hmac
import hashlib
import json
secret = b'your_shared_secret'
payload = json.dumps({'event': 'payment.success', 'amount': 1000}).encode('utf-8')
signature = hmac.new(secret, payload, hashlib.sha256).hexdigest()
# Inclua a assinatura no cabeçalho: X-Signature:
No lado receptor, você deve verificar a assinatura antes de processar o payload:
import hmac
import hashlib
def verify_signature(payload, received_signature, secret):
expected = hmac.new(secret, payload, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, received_signature)
Importante: Sempre use uma função de comparação de tempo constante como hmac.compare_digest para evitar ataques de temporização. Além disso, verifique a assinatura contra o corpo bruto da requisição, não uma versão parseada, porque a serialização JSON pode variar.
Melhores práticas para payloads assinados
- Use um segredo forte: Gere um segredo aleatório de pelo menos 32 bytes e armazene-o com segurança (ex.: variável de ambiente ou gerenciador de segredos).
- Inclua um timestamp: Adicione um timestamp ao payload assinado e rejeite requisições mais antigas que alguns minutos para prevenir ataques de replay.
- Use HTTPS: Sempre transmita webhooks via TLS para proteger o payload e a assinatura em trânsito.
- Rotacione segredos periodicamente: Suporte múltiplos segredos ativos durante a rotação para evitar indisponibilidade.
Lidando com falhas: Retentativas e idempotência
Webhooks podem falhar: seu servidor pode estar fora do ar, a rede pode cair ou seu endpoint pode retornar um erro. Um remetente confiável tentará reenviar a entrega, mas você deve projetar seu receptor para lidar com duplicatas e eventos fora de ordem.
Estratégias de retentativa
A maioria dos provedores de webhook usa backoff exponencial com jitter. Por exemplo, tente novamente após 1 minuto, depois 5 minutos, depois 30 minutos, até um número máximo de tentativas. Isso dá tempo ao seu sistema para se recuperar sem sobrecarregá-lo.
Se você está construindo o lado do remetente, implemente uma fila com retentativas agendadas. Armazene o payload e a contagem de tentativas e use um worker para processar as retentativas.
Idempotência: A chave para retentativas seguras
Como as retentativas podem causar entregas duplicadas, seu endpoint deve ser idempotente. Isso significa que processar o mesmo evento várias vezes deve ter o mesmo efeito que processá-lo uma vez.
Abordagens comuns:
- Use um ID de evento único: Inclua um ID no payload e armazene os IDs processados em um banco de dados. Ignore eventos com IDs que você já viu.
- Projete operações para serem idempotentes: Por exemplo, use upserts em vez de inserts, ou verifique se um recurso já existe antes de criá-lo.
Aqui está uma verificação de idempotência simples em Python:
def process_event(event_id, payload):
if db.exists('processed_events', event_id):
return # já processado
# processa o payload
db.insert('processed_events', event_id)
Garanta que a verificação e o processamento ocorram em uma única transação para evitar condições de corrida.
Comparação: Polling vs. Webhooks
| Aspecto | Polling | Webhooks |
|---|---|---|
| Latência | Depende do intervalo (ex.: 5 min) | Quase em tempo real |
| Carga no servidor | Requisições constantes mesmo sem mudanças | Requisições apenas em eventos |
| Complexidade | Simples de implementar | Requer assinatura, retentativas, idempotência |
| Confiabilidade | Você controla as retentativas | Depende da política de retentativa do remetente |
Passo a passo: Implementando um receptor de webhook seguro
- Configure um endpoint HTTPS que aceite requisições POST e leia o corpo bruto.
- Extraia o cabeçalho de assinatura (ex.:
X-Signature) e o cabeçalho de timestamp, se presente. - Verifique a assinatura usando HMAC e seu segredo. Rejeite se inválida.
- Verifique o timestamp para prevenir ataques de replay (ex.: rejeite se for mais antigo que 5 minutos).
- Faça o parse do payload e extraia o ID do evento.
- Verifique a idempotência procurando o ID do evento no seu banco de dados.
- Processe o evento dentro de uma transação que também registre o ID do evento.
- Retorne um status 2xx rapidamente para confirmar o recebimento. Se o processamento demorar, enfileire o trabalho e retorne 202 Accepted.
Testando sua implementação de webhook
Use ferramentas como ngrok para expor seu servidor local e simular webhooks. Escreva testes unitários para verificação de assinatura, idempotência e lógica de retentativa. Por exemplo, teste que um ID de evento duplicado é ignorado e que uma assinatura inválida retorna 401.
Ao depurar, registre o payload e a assinatura recebidos (mas nunca registre segredos). Se você estiver trabalhando com payloads JSON, um formatador JSON pode ajudar a inspecionar e validar a estrutura rapidamente.
Perguntas Frequentes
O que é um payload de webhook assinado?
Um payload assinado inclui uma assinatura criptográfica (geralmente HMAC) calculada sobre o corpo da requisição com um segredo compartilhado. O receptor verifica a assinatura para garantir que a requisição é autêntica e não foi alterada.
Quantas vezes um webhook deve ser retentado?
Não há um número universal, mas a prática comum é de 3 a 5 retentativas com backoff exponencial. Depois disso, o evento geralmente é marcado como falho e pode exigir intervenção manual ou uma fila de mensagens mortas (dead-letter queue).
Posso usar webhooks sem HTTPS?
Você nunca deve usar webhooks sobre HTTP simples. Sem TLS, atacantes podem interceptar o payload e a assinatura, e reenviar ou modificar requisições. Sempre use HTTPS.
Pronto para inspecionar e formatar payloads de webhook? Experimente nosso formatador JSON gratuito para validar e embelezar dados JSON instantaneamente.