Webhooks Explicados: Payloads Assinados e Retries Confiáveis

Backend2026-11-11TryQuickToolBox

Você lança uma integração de pagamento e tudo funciona no ambiente de staging. Então, em produção, um cliente paga, seu endpoint dá timeout por dois segundos e o pedido nunca é ativado. Enquanto isso, o provedor de pagamento tenta reenviar o mesmo evento três vezes, e seu app cria três pedidos duplicados para o que deu certo. Webhooks parecem simples — apenas um HTTP POST —, mas as partes difíceis são confiança e garantias de entrega.

Este artigo cobre as duas coisas que mais quebram integrações de webhook: verificar que a requisição realmente veio do remetente e lidar com retries sem duplicar efeitos colaterais.

O que um webhook realmente é

Um webhook é uma chamada de API reversa. Em vez de seu servidor fazer polling no provedor a cada minuto perguntando "tem algo novo?", o provedor envia uma requisição HTTP para uma URL que você registrou quando um evento acontece. O payload geralmente é JSON, e o tipo de evento fica no corpo ou em um header.

POST /webhooks/payments HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-Event-Id: evt_8f2c1a
X-Timestamp: 1735689600
X-Signature: t=1735689600,v1=5d41402abc4b2a76b9719d911017c592

{
  "id": "evt_8f2c1a",
  "type": "payment.succeeded",
  "created": 1735689600,
  "data": { "order_id": "ord_123", "amount": 4999, "currency": "USD" }
}

Duas decisões de design importam no lado do remetente e você deve verificar ambas ao avaliar qualquer provedor: ele assina o payload? Ele tenta reenviar em caso de falha?

Por que webhooks sem assinatura são perigosos

Sua URL de webhook é pública. Qualquer pessoa que a descubra pode enviar um POST falso de payment.succeeded e marcar um pedido não pago como pago. Uma allowlist de IP ajuda um pouco, mas provedores mudam de IP, rodam atrás de CDNs e você pode não ter uma lista estável.

A resposta robusta é uma assinatura HMAC sobre o corpo bruto da requisição usando um segredo compartilhado que só você e o provedor conhecem. O provedor calcula a assinatura e a envia em um header; você recalcula e compara.

Verificando uma assinatura corretamente

Três detalhes são fáceis de errar:

// Exemplo Node.js / Express
const crypto = require('crypto');

function verifySignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(
    header.split(',').map(p => p.split('='))
  );
  const timestamp = Number(parts.t);
  if (!timestamp) return false;

  // Rejeita requisições antigas (proteção contra replay)
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > toleranceSeconds) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post('/webhooks/payments', express.raw({ type: '*/*' }), (req, res) => {
  if (!verifySignature(req.body.toString(), req.get('X-Signature'), SECRET)) {
    return res.status(401).send('invalid signature');
  }
  const event = JSON.parse(req.body.toString());
  // ... trata o evento
  res.status(200).send('ok');
});

Note o middleware express.raw(). Se você montar express.json() antes desta rota, o corpo já estará parseado e a verificação da assinatura falhará silenciosamente — um bug muito comum.

Projetando retries que não perdem eventos

A entrega de webhooks é at-least-once, não exactly-once. Redes falham, seu deploy reinicia um contêiner e o provedor não tem ideia se sua resposta 200 foi real. Então o provedor tenta novamente com backoff exponencial, muitas vezes por horas ou dias.

Responda rápido, processe depois

Seu endpoint deve fazer o mínimo: verificar, persistir o evento bruto, retornar 2xx. Trabalho pesado — enviar e-mails, chamar outras APIs, gerar faturas — deve acontecer em um job em background. Se o processamento demorar mais que o timeout do provedor, a requisição é tratada como falha e reenviada mesmo que você tenha feito o trabalho.

  1. Verifique a assinatura e o timestamp.
  2. Insira o evento em uma tabela com uma restrição única no ID do evento.
  3. Retorne 200 imediatamente.
  4. Processe o evento armazenado de forma assíncrona, marcando-o como concluído.

Idempotência: a correção real para duplicatas

Como os retries acontecem, seu handler deve ser seguro para rodar duas vezes. O ID do evento é a chave de idempotência natural.

INSERT INTO webhook_events (event_id, type, payload, received_at)
VALUES ($1, $2, $3, now())
ON CONFLICT (event_id) DO NOTHING;

Se o insert afetar zero linhas, você já viu este evento antes — confirme o recebimento e siga em frente. Para a lógica de negócio, aplique a mesma ideia: use o ID do pedido como chave única ao ativar um pagamento, para que um segundo evento não crie uma segunda ativação.

Escolhendo códigos de status intencionalmente

StatusComportamento do provedorQuando usar
200 / 204Marca como entregueEvento aceito (mesmo se já processado)
400Geralmente sem retryPayload malformado que você nunca conseguirá tratar
401Geralmente sem retryAssinatura não confere — verifique seu segredo
429Retry com backoffVocê está aplicando rate limiting
500 / 503Retry com backoffFalha temporária, banco fora do ar, deploy em andamento

Retornar 200 para um evento que você não conseguiu armazenar é a pior opção: o provedor para de tentar e o evento se perde para sempre. Retorne um 5xx e deixe o retry fazer seu trabalho.

Checklist prático para produção

Testando webhooks localmente

Você não consegue receber facilmente um POST público em localhost. Opções: uma ferramenta de tunelamento que exponha sua porta de desenvolvimento, a CLI do provedor se ele tiver uma, ou um pequeno script que envia um payload assinado para seu handler para você exercitar o caminho de verificação.

O teste mais valioso é o da duplicata: envie o mesmo evento duas vezes e confirme que seu sistema termina no mesmo estado. Depois envie um evento com um timestamp antigo e confirme que ele é rejeitado. Em seguida, altere um byte do corpo e confirme que a verificação da assinatura falha.

Depurando payloads

Corpos de webhook são JSON, e payloads malformados ou profundamente aninhados são dolorosos de ler em logs. Um formatador ajuda a inspecionar a estrutura rapidamente antes de escrever código de parsing. O formatador JSON roda no navegador, então você pode colar um payload capturado sem enviar dados de clientes para um servidor.

FAQ

Qual é a diferença entre um webhook e uma API?

Uma API é baseada em pull: seu código chama o provedor quando precisa de dados. Um webhook é baseado em push: o provedor chama seu endpoint quando um evento acontece. A maioria das integrações usa ambos — webhooks para notificações de eventos e a API para buscar detalhes completos ou executar ações.

Por que minha assinatura HMAC nunca confere?

A causa usual é assinar um corpo re-serializado em vez dos bytes brutos. Espaços em branco, ordem das chaves e escape de unicode alteram o hash. Leia o corpo bruto da requisição antes de qualquer middleware JSON e confirme que o segredo e o algoritmo de hash correspondem à documentação do provedor.

Os retries de webhook são garantidos?

Não. Provedores normalmente tentam novamente por uma janela limitada com backoff exponencial e então desistem. Trate webhooks como um canal de notificação rápida em vez de fonte da verdade: reconcilie periodicamente com a API do provedor para que eventos perdidos sejam eventualmente corrigidos.

Se você está construindo ou depurando um receptor de webhook hoje, comece bloqueando a verificação de assinatura e o armazenamento idempotente — essas duas mudanças eliminam a maioria dos incidentes reais com webhooks.