Webhooks Explicados: Payloads Assinados e Retries Confiáveis
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:
- Use o corpo bruto. Faça o parse do JSON somente após a verificação. Re-serializar um objeto já parseado altera espaços em branco e a ordem das chaves, então a assinatura nunca vai bater.
- Compare em tempo constante. Uma comparação ingênua de strings vaza informações de timing. Use uma função timing-safe.
- Inclua o timestamp na string assinada. Assinar
timestamp.bodypermite rejeitar requisições antigas e bloqueia ataques de replay.
// 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.
- Verifique a assinatura e o timestamp.
- Insira o evento em uma tabela com uma restrição única no ID do evento.
- Retorne
200imediatamente. - 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
| Status | Comportamento do provedor | Quando usar |
|---|---|---|
| 200 / 204 | Marca como entregue | Evento aceito (mesmo se já processado) |
| 400 | Geralmente sem retry | Payload malformado que você nunca conseguirá tratar |
| 401 | Geralmente sem retry | Assinatura não confere — verifique seu segredo |
| 429 | Retry com backoff | Você está aplicando rate limiting |
| 500 / 503 | Retry com backoff | Falha 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
- Use apenas HTTPS; nunca aceite webhooks via HTTP puro.
- Armazene o segredo de assinatura no seu gerenciador de segredos e suporte rotação — muitos provedores permitem dois segredos ativos.
- Registre em log o ID do evento, tipo, resultado da assinatura e desfecho do processamento para cada requisição.
- Defina uma janela de tolerância (cinco minutos é o típico) para bloquear replays.
- Torne os handlers idempotentes no nível do banco de dados, não apenas no código da aplicação.
- Dispare alertas quando a taxa de falha ou o atraso de processamento cruzar um limite.
- Forneça um endpoint de replay manual para a equipe de suporte.
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.