Webhooks Explicados: Payloads Assinados e Retentativas

Backend2026-11-14TryQuickToolBox

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:

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:

Comparação: Payloads Assinados vs. Basic Auth

AbordagemSegurançaComplexidadeProteção contra Replay
Basic AuthBaixa (credenciais enviadas a cada vez)BaixaNão
Payload Assinado (HMAC)AltaMédiaSim (com timestamp)

Passo a Passo: Construindo um Remetente de Webhook com Retentativas

  1. Defina o payload do evento e inclua um ID de evento único e timestamp.
  2. Calcule a assinatura usando HMAC-SHA256 sobre o corpo bruto.
  3. Envie a requisição com a assinatura em um cabeçalho.
  4. Lide com falhas retentando com backoff exponencial.
  5. 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.