Webhooks Explicados: Payloads Assinados e Retentativas

Você construiu uma API e agora precisa notificar outros serviços quando eventos acontecem. Você configurou um endpoint de webhook, mas rapidamente percebe que entregar requisições HTTP de forma confiável é mais difícil do que parece. Falhas de rede, agentes maliciosos e eventos duplicados podem causar caos. Este guia explica como implementar webhooks com payloads assinados e retentativas para que você possa construir uma integração robusta.

O que são Webhooks?

Webhooks são callbacks HTTP definidos pelo usuário. Quando um evento ocorre em sua aplicação, você envia uma requisição HTTP POST para uma URL fornecida pelo assinante. Isso permite comunicação em tempo real entre serviços sem polling.

Por exemplo, um processador de pagamentos pode enviar um webhook para sua aplicação quando uma cobrança é bem-sucedida. Sua aplicação pode então atualizar o status do pedido imediatamente.

Por que assinar payloads de webhook?

Endpoints de webhook são publicamente acessíveis, então qualquer pessoa pode enviar requisições falsas. Sem verificação, sua aplicação pode processar eventos fraudulentos. Assinar payloads garante que a requisição se originou do seu serviço e não foi adulterada.

A assinatura normalmente usa um segredo compartilhado entre remetente e destinatário. O remetente calcula um código de autenticação de mensagem baseado em hash (HMAC) sobre o payload e o inclui em um cabeçalho. O destinatário recalcula o HMAC e compara.

Como gerar e verificar assinaturas

A maioria das implementações usa HMAC-SHA256. Aqui está um exemplo simples em Python:

import hmac
import hashlib
import json

def generate_signature(payload, secret):
    body = json.dumps(payload, separators=(',', ':')).encode('utf-8')
    signature = hmac.new(secret.encode('utf-8'), body, hashlib.sha256).hexdigest()
    return signature

def verify_signature(payload, signature, secret):
    expected = generate_signature(payload, secret)
    return hmac.compare_digest(expected, signature)

Ao enviar o webhook, inclua a assinatura em um cabeçalho como X-Signature. O destinatário extrai o corpo bruto, recalcula o HMAC e compara. Sempre use uma função de comparação de tempo constante para prevenir ataques de temporização.

Implementando retentativas para entrega confiável

Webhooks são enviados pela internet, então falhas são inevitáveis. Seu servidor pode estar fora do ar, a rede pode estar lenta ou o assinante pode retornar um erro. Retentativas com backoff exponencial são essenciais.

Estratégia de retentativa

Uma abordagem comum é tentar novamente com atrasos crescentes: 1 minuto, 5 minutos, 30 minutos, 2 horas, etc. Pare após um número máximo de tentativas (por exemplo, 10) ou uma janela de tempo total (por exemplo, 24 horas).

Só tente novamente em condições específicas: erros de rede, respostas 5xx ou 429 (Too Many Requests). Não tente novamente em erros 4xx (exceto 429) porque eles indicam um erro do cliente que não será corrigido com retentativa.

Exemplo de lógica de retentativa

Aqui está um mecanismo de retentativa simplificado em Python usando a biblioteca requests:

import requests
import time
from requests.exceptions import RequestException

def send_webhook(url, payload, secret, max_retries=5):
    headers = {'Content-Type': 'application/json'}
    signature = generate_signature(payload, secret)
    headers['X-Signature'] = signature
    
    for attempt in range(max_retries):
        try:
            response = requests.post(url, json=payload, headers=headers, timeout=10)
            if response.status_code < 500 and response.status_code != 429:
                return response.status_code
        except RequestException:
            pass
        
        # Backoff exponencial com jitter
        delay = (2 ** attempt) + (random.random() * 0.1)
        time.sleep(delay)
    
    return None  # Falhou após retentativas

Em produção, você armazenaria tentativas falhas em uma fila e as processaria de forma assíncrona. Ferramentas como Celery ou filas em nuvem (AWS SQS, Google Cloud Tasks) podem ajudar.

Melhores práticas para segurança de webhooks

• Use HTTPS: Sempre envie webhooks sobre TLS para prevenir escutas.
• Inclua um timestamp: Adicione um timestamp ao payload e rejeite requisições mais antigas que alguns minutos para prevenir ataques de replay.
• Rotacione segredos: Periodicamente altere o segredo de assinatura e suporte múltiplos segredos ativos durante a rotação.
• Valide a URL: Ao registrar um webhook, garanta que a URL é acessível e retorna um 2xx para uma requisição de teste.
• Limitação de taxa: Proteja seu remetente de webhook contra abusos limitando o número de requisições por assinante.

Lidando com duplicatas e idempotência

Retentativas podem causar entregas duplicadas. Inclua um ID de evento único no payload e faça o destinatário rastrear IDs processados. Se um ID de evento já foi visto antes, ignore-o.

Alternativamente, projete seus manipuladores de eventos para serem idempotentes. Por exemplo, atualizar um registro com os mesmos dados várias vezes deve ter o mesmo efeito que fazer isso uma vez.

Testando webhooks

Use ferramentas como ngrok para expor seu servidor local e testar a entrega de webhooks. Simule falhas retornando códigos de erro e verifique se as retentativas ocorrem conforme esperado.

FAQ

O que é um payload de webhook assinado?

Um payload assinado inclui uma assinatura criptográfica (geralmente HMAC) que permite ao destinatário verificar que a requisição veio de uma fonte confiável e não foi alterada.

Quantas vezes devo tentar novamente um webhook falho?

Depende das suas necessidades de confiabilidade. Uma prática comum é 5-10 retentativas com backoff exponencial ao longo de 24 horas. Sempre permita que assinantes disparem manualmente uma retentativa.

Posso usar webhooks sem assinatura?

Você pode, mas é arriscado. Sem assinatura, qualquer pessoa pode enviar eventos falsos. Sempre assine webhooks em produção para prevenir fraudes.

Pronto para testar seus payloads de webhook? Use nosso JSON Formatter para validar e formatar payloads JSON antes de enviar.