Webhook: o que é, como funciona e como validar (HMAC)
Webhook é um POST que o sistema envia quando um evento acontece. Veja a diferença para API e polling, como validar a assinatura HMAC e evitar duplicatas.
Você integrou dois sistemas e tudo funciona, mas só porque a cada 30 segundos um job pergunta "tem novidade?". Na esmagadora maioria das vezes a resposta é "não". Você paga banda, CPU e cota de API para descobrir que nada mudou, e quando algo muda de fato o usuário espera até o próximo ciclo para ver. Esse desperdício tem nome, polling, e o jeito de acabar com ele é inverter a direção da conversa. É isso que um webhook faz.
Este post cobre três coisas: o que é um webhook e como ele se compara a uma API comum, como validar a assinatura HMAC de quem envia (com os headers reais de Stripe, GitHub e Mercado Pago) e como processar os eventos sem duplicar pagamento. Se você ainda está firmando a base de "o que é uma API", comece por O que é API.
O que é um webhook, em uma frase
Webhook é uma requisição HTTP, quase sempre um POST com corpo JSON, que um sistema envia automaticamente para uma URL sua quando um evento acontece. Em vez de você perguntar "o pagamento já entrou?", o gateway avisa no instante em que entra. A lógica se inverte: em vez de pull (você busca o dado), você recebe um push (o dado é empurrado até você).
Por isso webhook às vezes aparece como "reverse API" ou "callback HTTP". Você não chama o serviço; o serviço chama você.
Webhook vs API vs polling
A pergunta que mais aparece é "qual a diferença entre webhook e API?". A resposta curta: webhook não substitui API, ele muda quem toma a iniciativa.
| API (requisição sob demanda) | Polling | Webhook | |
|---|---|---|---|
| Quem inicia | Você | Você, em loop | O provedor |
| Quando o dado chega | Quando você pede | No próximo ciclo | Logo após o evento |
| Custo | Uma chamada por necessidade | Chamadas constantes, a maioria inútil | Uma chamada por evento |
| Exige URL pública | Não | Não | Sim |
| Quando usar | Ler ou alterar algo agora | Fonte sem webhook | Reagir a eventos |
Os números deixam o custo do polling claro. Para saber quando um pedido muda de status:
// Polling: a cada 30 segundos, pergunta se mudou algo
setInterval(async () => {
const resposta = await fetch('https://api.loja.com/pedidos/123');
const pedido = await resposta.json();
if (pedido.status === 'enviado') notificarCliente(pedido);
}, 30_000);
São 2.880 requisições por dia para um único pedido, e o status muda talvez uma vez. Com 10 mil pedidos abertos, são quase 29 milhões de chamadas por dia para quase nada. Com webhook você registra um endpoint uma vez e espera o evento chegar.
Na prática os dois convivem: o webhook avisa que algo mudou, e você usa a API para buscar o estado completo quando precisa. A própria Stripe recomenda isso para eventos que chegam fora de ordem.
Como o fluxo funciona de ponta a ponta
- Registro. Você informa ao provedor (Stripe, GitHub, Mercado Pago) a URL que recebe as notificações e os eventos que interessam. Nesse momento ele gera um segredo de assinatura (na Stripe, começa com
whsec_). - Evento. Algo acontece do lado do provedor: pagamento aprovado, push no repositório, assinatura renovada.
- Entrega. O provedor monta o payload, calcula um HMAC dele com o segredo e faz o
POSTna sua URL, com a assinatura num header. - Processamento. Seu endpoint valida a assinatura, registra o evento e responde
2xx.
O detalhe que separa uma integração amadora de uma robusta está no passo 4. A entrega é at-least-once (pelo menos uma vez): se a sua resposta 2xx não chegar a tempo, o provedor considera a entrega falha, e o mesmo evento pode chegar de novo. Seu código precisa contar com isso.
Como validar a assinatura de um webhook (HMAC)
Sua URL de webhook é pública. Qualquer um que a descubra pode mandar um POST dizendo "pagamento aprovado". A defesa é a assinatura: o provedor calcula um HMAC-SHA256 do conteúdo com o segredo compartilhado, e você recalcula do seu lado e compara. HMAC é criptografia de chave simétrica (os dois lados têm o mesmo segredo); a diferença entre os modelos está em criptografia simétrica e assimétrica.
O nome do header e o que entra no cálculo variam por provedor:
| Provedor | Header | Formato | O que é assinado |
|---|---|---|---|
| Stripe | Stripe-Signature |
t=1492774577,v1=5257a8... |
{t}.{corpo bruto} |
| GitHub | X-Hub-Signature-256 |
sha256=7571... |
o corpo bruto |
| Mercado Pago | x-signature |
ts=1704908010,v1=618c... |
um "manifesto" com o data.id da query, o header x-request-id e o ts |
O código abaixo valida Stripe e GitHub. Rodei com o vetor de teste da documentação do GitHub (segredo It's a Secret to Everybody, corpo Hello, World!) e conferi o lado Stripe contra a biblioteca oficial stripe (Node), gerando o header com generateTestHeaderString e validando com constructEvent: os dois concordam, inclusive ao recusar um timestamp de 10 minutos atrás.
import crypto from 'node:crypto';
function compararHex(esperadaHex, recebidaHex) {
const a = Buffer.from(esperadaHex, 'hex');
const b = Buffer.from(recebidaHex, 'hex');
// timingSafeEqual lança RangeError se os tamanhos forem diferentes
if (a.length === 0 || a.length !== b.length) return false;
return crypto.timingSafeEqual(a, b);
}
// GitHub: X-Hub-Signature-256: sha256=<hex>
export function validarGitHub(corpoBruto, header, segredo) {
if (typeof header !== 'string' || !header.startsWith('sha256=')) return false;
const esperada = crypto.createHmac('sha256', segredo).update(corpoBruto).digest('hex');
return compararHex(esperada, header.slice('sha256='.length));
}
// Stripe: Stripe-Signature: t=<unix>,v1=<hex>[,v1=<hex>...]
export function validarStripe(corpoBruto, header, segredo, toleranciaSeg = 300) {
const pares = String(header ?? '').split(',').map((p) => p.split('='));
const t = Number(pares.find(([k]) => k === 't')?.[1]);
const assinaturas = pares.filter(([k]) => k === 'v1').map(([, v]) => v);
if (!Number.isFinite(t) || assinaturas.length === 0) return false;
if (Math.abs(Date.now() / 1000 - t) > toleranciaSeg) return false; // replay
const esperada = crypto.createHmac('sha256', segredo).update(`${t}.${corpoBruto}`).digest('hex');
return assinaturas.some((s) => compararHex(esperada, s));
}
Quatro detalhes que derrubam implementações caseiras:
timingSafeEqualexige buffers do mesmo tamanho. Se você comparar a stringsha256=...do GitHub com o hex puro, o Node lançaRangeError: Input buffers must have the same byte lengthe o seu handler responde 500 em vez de 401. Tire o prefixo e cheque o tamanho antes. A comparação de tempo constante existe para não vazar, pelo tempo de resposta, quantos bytes da assinatura batem; a doc do GitHub diz para nunca usar==puro.- Assine o corpo bruto, não o JSON re-serializado. No meu teste, o mesmo payload reformatado com
JSON.stringifyfalhou na validação. No Express, useexpress.raw({ type: 'application/json' })na rota do webhook e só façaJSON.parsedepois de validar. - Cheque o timestamp. O
tda Stripe entra no cálculo, então não dá para alterá-lo sem quebrar a assinatura; recusar timestamps antigos impede que alguém reenvie uma requisição válida capturada (replay). As bibliotecas da Stripe usam tolerância padrão de cinco minutos, e a doc avisa para nunca usar tolerância zero. O GitHub não manda timestamp: lá a proteção contra replay é guardar oX-GitHub-Delivery, um ID único por entrega. - Ignore esquemas que não sejam
v1. A Stripe manda umv0falso em eventos de teste e pede explicitamente para ignorá-lo (proteção contra downgrade). Durante a rotação de segredo podem vir doisv1; basta um bater.
Se o provedor tem SDK oficial com validação pronta (Stripe e Mercado Pago têm), use o SDK. Escrever na mão vale para entender o que ele faz e para provedores que não oferecem biblioteca.
Responda rápido, processe depois
Os prazos documentados variam: o GitHub pede 2xx em até 10 segundos e, se passar disso, encerra a conexão e marca a entrega como falha; o Mercado Pago espera até 22 segundos; a Stripe não publica um número e só diz para responder 2xx rapidamente, antes de qualquer lógica que possa causar timeout. Se o seu handler consulta um banco lento, gera PDF e manda e-mail antes de responder, ele vai estourar o prazo de alguém.
A regra é: valide, enfileire e responda. O trabalho pesado vai para um worker.
import express from 'express';
const app = express();
app.post('/webhooks/github', express.raw({ type: 'application/json' }), async (req, res) => {
if (!validarGitHub(req.body, req.get('X-Hub-Signature-256'), process.env.GITHUB_WEBHOOK_SECRET)) {
return res.sendStatus(401);
}
await fila.enqueue({
entregaId: req.get('X-GitHub-Delivery'),
evento: req.get('X-GitHub-Event'),
payload: JSON.parse(req.body),
});
res.sendStatus(202);
});
Testei esse handler com uma fila em memória: assinatura válida devolve 202, assinatura errada ou ausente devolve 401, e o corpo reformatado devolve 401.
O que acontece depois de uma falha também muda por provedor, e vale saber antes do primeiro incidente:
- Stripe: em produção, retenta por até três dias com backoff exponencial; em sandbox, três vezes em poucas horas. Também dá para reenviar manualmente pelo painel (até 15 dias) ou pela CLI (
stripe events resend, até 30 dias). - GitHub: não reentrega falhas automaticamente. Depois de uma queda, você precisa reenviar as entregas perdidas pela interface ou pela API REST.
- Mercado Pago: reenvia a cada 15 minutos; depois da terceira tentativa o intervalo aumenta, mas os envios continuam.
Idempotência e ordem dos eventos
Como a entrega é pelo menos uma vez, o mesmo evento pode chegar duas vezes, e a Stripe avisa que não garante a ordem: invoice.paid pode chegar antes de invoice.created. A solução é um handler idempotente: cada evento tem um ID único (o id do evento na Stripe, o X-GitHub-Delivery no GitHub), e você registra os IDs já processados.
async function processarEvento(evento) {
// INSERT ... ON CONFLICT DO NOTHING devolve 0 linhas se o ID já existe
const novo = await db.registrarEventoSeNovo(evento.id);
if (!novo) return; // duplicata: já foi tratada
await aplicarRegraDeNegocio(evento);
}
Faça o registro do ID e o efeito colateral na mesma transação quando puder. Se você marca o ID como processado e o efeito falha, perdeu o evento; se aplica o efeito e cai antes de marcar, processa duas vezes. E não use o timestamp do evento para decidir a ordem: a Stripe registra created em segundos, então dois eventos podem ter o mesmo valor. Quando a ordem importa, busque o estado atual do objeto na API.
Como testar webhooks localmente
O problema clássico: o provedor precisa de uma URL pública e o seu código roda em localhost. O caminho mais curto é a CLI do próprio provedor. A Stripe tem stripe listen --forward-to localhost:4242/webhook, que encaminha eventos para a sua máquina e imprime o segredo de assinatura daquela sessão; stripe trigger payment_intent.succeeded dispara um evento de teste. No GitHub, o encaminhamento não é comando nativo do gh: é a extensão cli/gh-webhook.
gh extension install cli/gh-webhook
gh webhook forward --repo=minha-org/meu-repo --events=push,pull_request --url="http://localhost:3000/webhooks/github"
Pela doc do GitHub, a extensão só funciona com webhooks de repositório e de organização, foi feita só para teste e desenvolvimento, e só uma pessoa por vez pode usá-la em cada repositório. Para os outros casos:
- Túnel local.
ngrokoucloudflaredexpõem sua porta com uma URL HTTPS temporária, que você cadastra no painel do provedor. Serve para qualquer provedor. - Inspetor de requisições. Sites como webhook.site dão uma URL descartável que mostra o payload e os headers recebidos, bom para entender o formato antes de escrever código.
Para transformar esses testes manuais em suíte que roda no CI, o caminho está em testar APIs de forma automatizada. Salve um payload real de cada evento como fixture e teste o handler contra ele, inclusive com assinatura errada e evento duplicado.
Onde webhooks fazem sentido (e onde não)
Webhooks são a escolha certa para confirmação assíncrona de pagamento, CI/CD (um push dispara o pipeline), integrações no-code via Zapier ou Make e avisos em chat (deploy concluído avisa o Slack).
Não servem quando o consumidor não tem endpoint público, como um app mobile; aí entram push notifications ou polling. Também não servem quando você precisa de comunicação bidirecional contínua, como um chat: isso é WebSocket. Entre microsserviços seus, onde você controla os dois lados, uma fila (RabbitMQ, Kafka, SQS) costuma ser melhor que webhook HTTP, porque já dá persistência e retry; se mesmo assim os serviços conversarem por HTTP, testes de contrato evitam que uma mudança no payload quebre o consumidor em silêncio.
E o endpoint que recebe o webhook é um endpoint HTTP como outro qualquer: status codes, versionamento e formato de erro seguem as mesmas boas práticas de API REST.
Perguntas frequentes
Qual a diferença entre webhook e API?
Numa API você faz a requisição e recebe a resposta na hora (pull). No webhook, o servidor chama você quando um evento acontece (push). O webhook é entregue por HTTP, então tecnicamente é uma chamada de API, mas a iniciativa é invertida. Use a API quando precisa do dado agora e o webhook quando quer ser avisado quando o dado mudar.
Qual a diferença entre webhook e WebSocket?
Webhook é uma requisição HTTP avulsa, de servidor para servidor, disparada a cada evento. WebSocket é uma conexão persistente e bidirecional, normalmente entre navegador e servidor, usada para chat, dashboards ao vivo e jogos. Se o destinatário é um backend que reage a eventos, é webhook; se é uma tela aberta que precisa de atualização contínua, é WebSocket ou Server-Sent Events.
Webhook é seguro?
Pode ser, se você fizer três coisas: aceitar só HTTPS (a Stripe exige HTTPS em produção), validar a assinatura de toda requisição com comparação de tempo constante e checar timestamp ou ID de entrega contra replay. Sem validar a assinatura, qualquer pessoa que descubra a URL forja eventos. A Stripe também publica a lista de IPs de onde envia webhooks, e filtrar por IP é uma camada a mais, não um substituto da assinatura.
O que acontece se meu servidor estiver fora do ar quando o evento dispara?
Depende do provedor. A Stripe retenta por até três dias em produção, o Mercado Pago reenvia a cada 15 minutos, e o GitHub não retenta sozinho: você precisa reenviar as entregas perdidas. Em todos os casos, projete uma reconciliação: um job que, depois de uma queda, lista os eventos ou objetos pela API e processa o que ficou para trás.
Valide, enfileire, deduplique
Webhook é só um POST no momento certo em vez de milhares de GET no escuro. O que faz a integração aguentar produção são três hábitos: validar a assinatura sobre o corpo bruto, com comparação de tempo constante e checagem de timestamp; responder 2xx em segundos e mandar o trabalho pesado para uma fila; e tratar cada evento pelo ID, porque ele vai chegar duplicado e fora de ordem em algum momento. Antes de integrar um provedor novo, leia a página de webhooks dele procurando três respostas: qual header assina, qual o prazo de resposta e qual a política de retry.
O conteúdo editorial termina aqui. Para ler um payload de webhook capturado no inspetor ou no log, colo o JSON no formatador de JSON do Quick Tools, que indenta, valida e mostra a estrutura em árvore. Ele só formata: a validação da assinatura continua sendo no seu código.
- 01 Nota do PageSpeed influencia o SEO? 100/100 e reprovado O Google não usa a nota de 0 a 100 do PageSpeed no ranking, e sim os Core Web Vitals de usuários reais. Veja por que dá 100/100 e reprova no campo.
- 02 Teste unitário vs teste de integração: diferença na prática A diferença entre teste unitário e de integração com exemplos de API e banco de dados: o que cada um pega, quanto custa e quando usar cada um no seu projeto.