Webhooks Explicados: Payloads Assinados e Estratégias de Retry

Backend2026-11-12TryQuickToolBox

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

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:

TentativaAtraso
1Imediato
21 minuto
35 minutos
430 minutos
52 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

  1. Defina eventos e estrutura do payload: Documente os eventos que seu sistema emite e o schema JSON para cada um.
  2. Gere um segredo: Crie um segredo único por endpoint de webhook e compartilhe-o com segurança.
  3. Assine cada requisição: Calcule HMAC sobre o payload e o timestamp, inclua nos headers.
  4. Implemente retries com backoff: Use um sistema de filas para agendar retries.
  5. Forneça uma forma de verificar assinaturas: Documente o processo de verificação para os receptores.
  6. Monitore e registre: Acompanhe tentativas de entrega e falhas para depuração.

Armadilhas Comuns e Como Evitá-las

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.