O que é um webhook e como funciona: o guia definitivo

Webhook é a forma mais simples de um sistema avisar outro que algo aconteceu: em vez de você perguntar de tempos em tempos se há novidade, o serviço envia uma requisição HTTP para a sua aplicação no momento exato em que o evento ocorre. Neste guia você vai entender como isso funciona por baixo dos panos, quando usar (e quando não usar) e o que uma implementação séria precisa ter.

A analogia da campainha

Imagine que você pediu uma encomenda. Existem duas formas de saber se ela chegou: abrir a porta a cada cinco minutos para conferir, ou instalar uma campainha e deixar que o entregador toque quando chegar. Consultar uma API repetidamente (polling) é abrir a porta a cada cinco minutos. Webhook é a campainha: você informa um endereço e o outro lado se encarrega de avisar.

Tecnicamente, um webhook é uma requisição HTTP — quase sempre um POST com corpo JSON — que um provedor (Stripe, GitHub, Mercado Pago, Shopify…) envia para uma URL que você cadastrou. Essa URL é um endpoint da sua aplicação, público na internet, preparado para receber e processar esses avisos.

Como um webhook funciona, passo a passo

1. Você cadastra uma URL no painel ou na API do provedor — por exemplo, https://sua-app.com/webhooks/pagamentos — e escolhe quais eventos quer receber (pagamento aprovado, pedido criado, push no repositório…).
2. O evento acontece do lado do provedor: um cliente paga um boleto, um Pix é confirmado, alguém abre um pull request.
3. O provedor monta um payload — um JSON descrevendo o evento — e envia um POST para a sua URL, geralmente com headers de identificação e uma assinatura criptográfica.
4. Sua aplicação responde com um status 2xx para confirmar o recebimento. Qualquer outra resposta (ou demora) é tratada como falha.
5. Se a entrega falha, o provedor tenta de novo — normalmente com intervalos crescentes (backoff exponencial) durante horas ou dias.

Um exemplo real de payload

A estrutura varia por provedor, mas quase todos seguem o mesmo padrão de envelope: um identificador do evento, o tipo, a data e os dados em si. Um webhook de pagamento típico se parece com isto:

{
  "id": "evt_1QxK2mLkdIwHu7ix",
  "type": "payment.approved",
  "created_at": "2026-07-25T14:32:07Z",
  "data": {
    "payment_id": "pay_9f8e7d6c",
    "amount": 14990,
    "currency": "BRL",
    "method": "pix",
    "customer_email": "cliente@exemplo.com"
  }
}

Repare em dois detalhes que aparecem em praticamente todo provedor sério: o id do evento (que permite detectar duplicatas) e o type (que permite rotear o processamento). Os headers que acompanham essa requisição — assinatura, identificador de entrega, content-type — merecem um capítulo próprio: dissecamos tudo em Anatomia de uma requisição de webhook.

Webhook vs. API: qual a diferença?

Webhook não substitui API — os dois se complementam e a direção da comunicação é o que muda. Na API, você pergunta; no webhook, eles avisam.

Uma arquitetura madura costuma usar os dois: webhooks para reagir rápido e uma rotina de reconciliação via API (por exemplo, a cada hora) para cobrir qualquer evento que se perca no caminho.

Onde webhooks aparecem no dia a dia

• Pagamentos — Stripe, Mercado Pago, PagSeguro e afins avisam quando um Pix é confirmado, um cartão é recusado ou uma assinatura é cancelada.
• Git e CI/CD — GitHub e GitLab disparam webhooks a cada push, pull request ou release, e é assim que pipelines de deploy começam.
• Mensageria — WhatsApp Business, Telegram e Slack entregam mensagens recebidas via webhook.
• Infoprodutos e e-commerce — Hotmart, Kiwify e Shopify notificam vendas, reembolsos e mudanças de status de pedido.
• Automação — Zapier, Make e n8n são, na essência, roteadores de webhooks entre serviços.

O que uma implementação séria precisa ter

Receber um POST é fácil; operar webhooks em produção com confiabilidade é onde mora a complexidade. Os pontos essenciais:

• Responda rápido, processe depois. Confirme com 200 em milissegundos e jogue o trabalho pesado numa fila. Provedores costumam ter timeout de 5 a 30 segundos — estourou, conta como falha e vem retry.
• Seja idempotente. Retries garantem entrega pelo menos uma vez, o que significa que o mesmo evento pode chegar duas vezes. Guarde o id do evento e ignore duplicatas.
• Valide a assinatura. Seu endpoint é público; qualquer um pode enviar um POST para ele. A assinatura HMAC é o que separa um evento legítimo de uma fraude — explicamos o mecanismo completo em Segurança de webhooks: assinatura HMAC e boas práticas.
• Não confie na ordem. Um retry pode fazer o evento "criado" chegar depois do "atualizado". Use o timestamp do evento (ou consulte a API) como fonte de verdade do estado atual.
• Monitore e tenha replay. Falhas silenciosas de webhook são notórias: tudo parece funcionar até alguém perceber que os pedidos pararam de cair no sistema. Registre cada entrega e tenha como reprocessar.

Como começar a experimentar

A melhor forma de entender webhooks é ver um chegando. O caminho mais curto: aponte o webhook de teste do provedor para um endpoint de inspeção — uma URL temporária que captura e exibe cada requisição recebida, com headers e body formatados (o SafeHook faz exatamente isso, e há outras opções que comparamos adiante). Dispare um evento de teste e examine o que chega antes de escrever uma linha de código.

Quando for desenvolver o endpoint de verdade na sua máquina, você vai esbarrar no clássico "o provedor não alcança o meu localhost" — os caminhos para resolver isso (túneis, encaminhamento e CLIs) estão em Como testar webhooks em localhost. E antes de ir para produção, vale conferir os 10 erros mais comuns ao implementar webhooks — quase todos são evitáveis com decisões simples tomadas cedo.

Resumo

• Webhook é o provedor chamando você via HTTP quando um evento acontece — a campainha, não a vigília na porta.
• O contrato básico: POST com JSON, resposta 2xx rápida, retries com backoff em caso de falha.
• Produção exige assinatura validada, idempotência, fila de processamento e monitoramento.
• Webhook notifica; a API confirma. Use os dois.