Webhooks Explicados: Payloads Assinados e Retentativas para Integrações Confiáveis

Backend2026-11-13TryQuickToolBox

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

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:

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

AspectoPollingWebhooks
LatênciaDepende do intervalo (ex.: 5 min)Quase em tempo real
Carga no servidorRequisições constantes mesmo sem mudançasRequisições apenas em eventos
ComplexidadeSimples de implementarRequer assinatura, retentativas, idempotência
ConfiabilidadeVocê controla as retentativasDepende da política de retentativa do remetente

Passo a passo: Implementando um receptor de webhook seguro

  1. Configure um endpoint HTTPS que aceite requisições POST e leia o corpo bruto.
  2. Extraia o cabeçalho de assinatura (ex.: X-Signature) e o cabeçalho de timestamp, se presente.
  3. Verifique a assinatura usando HMAC e seu segredo. Rejeite se inválida.
  4. Verifique o timestamp para prevenir ataques de replay (ex.: rejeite se for mais antigo que 5 minutos).
  5. Faça o parse do payload e extraia o ID do evento.
  6. Verifique a idempotência procurando o ID do evento no seu banco de dados.
  7. Processe o evento dentro de uma transação que também registre o ID do evento.
  8. 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.