Todos os artigos
176 artigos · atualizado semanalmente Veja nossas Ferramentas
Todos os artigos
Todos

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.

Webhook: o que é, como funciona e como validar (HMAC)
COVER · Todos

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

  1. 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_).
  2. Evento. Algo acontece do lado do provedor: pagamento aprovado, push no repositório, assinatura renovada.
  3. Entrega. O provedor monta o payload, calcula um HMAC dele com o segredo e faz o POST na sua URL, com a assinatura num header.
  4. 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:

  • timingSafeEqual exige buffers do mesmo tamanho. Se você comparar a string sha256=... do GitHub com o hex puro, o Node lança RangeError: Input buffers must have the same byte length e 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.stringify falhou na validação. No Express, use express.raw({ type: 'application/json' }) na rota do webhook e só faça JSON.parse depois de validar.
  • Cheque o timestamp. O t da 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 o X-GitHub-Delivery, um ID único por entrega.
  • Ignore esquemas que não sejam v1. A Stripe manda um v0 falso em eventos de teste e pede explicitamente para ignorá-lo (proteção contra downgrade). Durante a rotação de segredo podem vir dois v1; 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. ngrok ou cloudflared expõ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.

RD
Autor
Rafael Duarte
Desenvolvedor backend com passagem por fintech e SaaS B2B — trabalhou em times que escalaram APIs de zero a milhões de requisições. Carrega cicatrizes de produção suficientes para ter opiniões fortes sobre ferramentas, padrões e decisões de arquitetura. Não é acadêmico: leu a RFC do UUID quando precisou escolher entre v4 e v7 para uma tabela de alta escrita.
Ver perfil