Webhooks Explicados: Payloads Assinados e Retentativas

Por que Webhooks São Poderosos e Frágeis ao Mesmo Tempo

Webhooks alimentam integrações em tempo real: notificações de pagamento, gatilhos de CI/CD, mensagens de chat. Mas eles vêm com dois grandes desafios: segurança (como saber que a requisição veio do remetente esperado?) e confiabilidade (e se o receptor estiver fora do ar?). Este artigo mostra como resolver ambos com payloads assinados e estratégias de retentativa.

O Que É um Webhook?

Um webhook é uma requisição HTTP POST enviada por um provedor a um consumidor quando um evento ocorre. Diferente do polling, webhooks enviam dados quase em tempo real, reduzindo latência e carga no servidor. O provedor deve garantir que a requisição é autêntica; o consumidor deve processá-la de forma confiável.

Protegendo Webhooks com Payloads Assinados

Um payload assinado usa uma chave secreta para criar uma assinatura criptográfica (geralmente HMAC-SHA256) do corpo da requisição. O receptor recalcula a assinatura e a compara com a que está no cabeçalho. Se coincidirem, o payload é autêntico e não foi adulterado.

Como Gerar e Verificar Assinaturas

Aqui está um fluxo típico:

1. Provedor e consumidor compartilham uma chave secreta (por exemplo, via painel).
2. O provedor calcula HMAC-SHA256(secret, payload) e envia em um cabeçalho como X-Signature.
3. O consumidor lê o corpo bruto, calcula o mesmo HMAC e compara usando uma função de tempo constante.

Exemplo em Node.js:

const crypto = require('crypto');

function verifySignature(secret, payload, signature) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(payload);
  const digest = hmac.digest('hex');
  return crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(signature));
}

Sempre use comparação de tempo constante para prevenir ataques de timing. Nunca faça o parse do corpo antes da verificação—use middleware de corpo bruto.

Implementando Retentativas para Entrega Confiável

Mesmo com assinaturas, falhas de rede ou indisponibilidades temporárias podem fazer a entrega do webhook falhar. Um mecanismo robusto de retentativa garante a entrega eventual.

Estratégias de Retentativa

• Backoff exponencial: Espere mais tempo entre cada tentativa (por exemplo, 1s, 2s, 4s, 8s).
• Máximo de tentativas: Limite as retentativas (por exemplo, 5 tentativas) para evitar loops infinitos.
• Fila de mensagens mortas: Após o máximo de tentativas, armazene o evento para inspeção manual.
• Idempotência: Inclua um ID de evento único para que o consumidor possa ignorar duplicatas.

Exemplo de lógica de retentativa em Python:

import time
import requests

def send_webhook(url, payload, max_retries=5):
    for attempt in range(max_retries):
        try:
            response = requests.post(url, json=payload, timeout=5)
            if response.status_code == 200:
                return True
        except requests.RequestException:
            pass
        time.sleep(2 ** attempt)  # exponential backoff
    return False

Melhores Práticas para Consumidores de Webhooks

• Responda com 2xx rapidamente; processe de forma assíncrona se necessário.
• Valide a assinatura antes de qualquer processamento.
• Use chaves de idempotência para lidar com entregas duplicadas.
• Registre todos os webhooks recebidos para depuração.
• Monitore falhas e alerte em erros repetidos.

Comparação: Polling vs Webhooks

FAQ

O que é um payload de webhook assinado?

Um payload assinado inclui uma assinatura criptográfica (por exemplo, HMAC) que permite ao receptor verificar que a requisição veio de uma fonte confiável e não foi adulterada.

Quantas vezes devo tentar novamente um webhook que falhou?

Não há um número universal, mas 3–5 tentativas com backoff exponencial é comum. Depois disso, registre o evento para revisão manual.

Posso usar JWT em vez de HMAC para assinaturas de webhook?

Sim, alguns provedores usam JWT. O princípio é o mesmo: verifique a assinatura e as claims do token antes de confiar no payload.

Precisa inspecionar payloads ou logs de webhook? Experimente nosso JSON Formatter para formatar e validar payloads JSON rapidamente.