Webhooks Explicados: Payloads Assinados e Retentativas
Você construiu uma API e agora precisa notificar outros serviços quando eventos acontecem. Polling é ineficiente, então você implementa webhooks. Mas logo percebe: como garantir que o payload é autêntico? E se o receptor estiver fora do ar? Sem as devidas proteções, webhooks podem se tornar uma brecha de segurança e um pesadelo de confiabilidade.
Neste artigo, vamos percorrer os fundamentos dos webhooks, focando em dois aspectos críticos: payloads assinados para segurança e mecanismos de retentativa para confiabilidade. Forneceremos exemplos práticos de código e boas práticas para ajudar você a construir sistemas de webhook robustos.
O que são Webhooks?
Webhooks são callbacks HTTP definidos pelo usuário. Eles permitem que um sistema envie dados em tempo real para outro quando um evento específico ocorre. Diferente de APIs onde você puxa dados, webhooks empurram dados para você. Isso os torna ideais para arquiteturas orientadas a eventos.
Casos de uso comuns incluem notificações de pagamento (ex.: Stripe), gatilhos de CI/CD (ex.: GitHub) e plataformas de mensagens (ex.: Slack). O remetente faz uma requisição HTTP POST para uma URL fornecida pelo receptor, com um payload contendo detalhes do evento.
Por que proteger Webhooks com Payloads Assinados?
Endpoints de webhook são publicamente acessíveis, tornando-os vulneráveis a falsificação. Um atacante poderia enviar payloads falsos para acionar ações não intencionais. Para evitar isso, os remetentes assinam o payload usando um segredo compartilhado. O receptor verifica a assinatura para garantir autenticidade e integridade.
A assinatura normalmente envolve gerar um HMAC (Hash-based Message Authentication Code) do payload usando uma chave secreta. A assinatura é enviada em um cabeçalho (ex.: X-Signature). O receptor recalcula o HMAC e compara com a assinatura recebida.
Como implementar Payloads Assinados
Vamos ver um exemplo simples em Python usando Flask. O remetente calcula a assinatura:
import hmac
import hashlib
import json
import requests
secret = b'your_shared_secret'
payload = {'event': 'payment.success', 'amount': 100}
body = json.dumps(payload).encode('utf-8')
signature = hmac.new(secret, body, hashlib.sha256).hexdigest()
headers = {'Content-Type': 'application/json', 'X-Signature': signature}
requests.post('https://receiver.com/webhook', data=body, headers=headers)
O receptor verifica a assinatura:
from flask import Flask, request, abort
import hmac
import hashlib
app = Flask(__name__)
secret = b'your_shared_secret'
@app.route('/webhook', methods=['POST'])
def webhook():
signature = request.headers.get('X-Signature')
body = request.get_data()
expected = hmac.new(secret, body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(signature, expected):
abort(401)
# Processar payload
return '', 200
Boas práticas:
- Use um segredo forte e rotacione-o periodicamente.
- Inclua um timestamp nos dados assinados para prevenir ataques de replay.
- Use
hmac.compare_digestpara comparação em tempo constante. - Assine o corpo bruto, não o JSON parseado, para evitar inconsistências.
Implementando Retentativas Confiáveis
A entrega de webhooks pode falhar devido a problemas de rede, indisponibilidade do receptor ou erros de processamento. Um sistema robusto deve retentar entregas falhas com backoff exponencial.
Estratégia de Retentativa
Abordagem comum: retentar até N vezes com atrasos crescentes (ex.: 1s, 5s, 30s, 5m, 30m). Após esgotar as retentativas, marcar a entrega como falha e alertar.
Aqui está um mecanismo simples de retentativa em Python usando a biblioteca requests e tenacity:
from tenacity import retry, stop_after_attempt, wait_exponential
import requests
@retry(stop=stop_after_attempt(5), wait=wait_exponential(multiplier=1, min=1, max=60))
def send_webhook(url, payload, signature):
headers = {'X-Signature': signature}
response = requests.post(url, json=payload, headers=headers, timeout=10)
response.raise_for_status()
return response
Boas práticas para retentativas:
- Use chaves de idempotência para permitir que os receptores dedupliquem.
- Defina um timeout para cada requisição para evitar travamentos.
- Registre cada tentativa para depuração.
- Forneça uma maneira de retentar manualmente a partir de um dashboard.
Comparação: Payloads Assinados vs. Basic Auth
| Abordagem | Segurança | Complexidade | Proteção contra Replay |
|---|---|---|---|
| Basic Auth | Baixa (credenciais enviadas a cada vez) | Baixa | Não |
| Payload Assinado (HMAC) | Alta | Média | Sim (com timestamp) |
Passo a Passo: Construindo um Remetente de Webhook com Retentativas
- Defina o payload do evento e inclua um ID de evento único e timestamp.
- Calcule a assinatura usando HMAC-SHA256 sobre o corpo bruto.
- Envie a requisição com a assinatura em um cabeçalho.
- Lide com falhas retentando com backoff exponencial.
- Registre as entregas e forneça visibilidade.
Testando Webhooks
Use ferramentas como ngrok para expor seu servidor local e testar a entrega de webhooks. Sempre verifique assinaturas em seus testes para detectar problemas precocemente.
FAQ
O que é um payload assinado em webhooks?
Um payload assinado é uma requisição de webhook onde o remetente inclui uma assinatura criptográfica (geralmente HMAC) gerada com um segredo compartilhado. O receptor verifica a assinatura para confirmar que a requisição é autêntica e não foi adulterada.
Quantas vezes devo retentar um webhook falho?
Não há um número fixo, mas a prática comum é de 3 a 5 retentativas com backoff exponencial. Considere o tempo de inatividade típico do seu receptor e a criticidade do evento. Sempre permita retentativas manuais.
Posso usar JWT para assinaturas de webhook?
Sim, JWT pode ser usado, mas é mais complexo. Assinaturas HMAC são mais simples e suficientes para a maioria dos casos. Se você precisar incluir claims, JWT pode ser adequado.
Pronto para testar seus payloads de webhook? Use nosso JSON Formatter para validar e formatar seus payloads JSON antes de enviar.