O que é webhook? Como funciona, exemplos e cuidados

O que é um webhook, em linguagem simples?

Imagine que você espera uma encomenda. Você pode ligar para a loja de hora em hora perguntando "já saiu?", ou pode pedir que a loja mande uma mensagem quando sair. O primeiro caminho é consultar. O segundo é um webhook: o próprio sistema avisa quando o evento acontece, e você não precisa ficar perguntando.

Na prática, o webhook é um endereço do seu sistema que outro sistema chama quando algo ocorre: pagamento aprovado, formulário enviado, mensagem recebida. O aviso chega como uma requisição pela internet, com os dados do evento em um formato de texto chamado JSON. Se a API é a porta que você abre para pedir algo a um sistema, o webhook é a campainha que o sistema toca quando tem algo a dizer.

A vantagem é dupla: a informação chega quase na hora, e você deixa de gastar requisições (e, em alguns serviços, limite de uso) perguntando "mudou alguma coisa?" a cada poucos minutos.

Onde uma empresa usa webhooks?

• Pagamento aprovado. A loja cria a cobrança e, quando o Pix ou o cartão é aprovado, o provedor de pagamento avisa por webhook. Só então o pedido é liberado, sem ninguém conferir o extrato. No Pix, a especificação da API Pix do Banco Central prevê que quem recebe cadastre uma URL para ser notificado quando um Pix ligado a uma cobrança (identificada por um txid) é recebido. Na prática, esse cadastro costuma ser feito pelo banco ou pelo provedor de pagamento.
• Formulário do site caindo no CRM. O site avisa o sistema de relacionamento com clientes a cada novo contato, e a equipe comercial recebe o lead sem copiar e colar.
• Mensagem recebida no WhatsApp. A API oficial do WhatsApp (Meta) usa webhooks para avisar sobre mensagens recebidas e sobre o status das mensagens enviadas. Um fluxo pode registrar o contato, abrir um atendimento ou responder automaticamente. Exige conta empresarial e segue as regras da Meta.

Em todos os casos o princípio é o mesmo: evento acontece, sistema avisa, o outro lado reage. É a base de boa parte da automação de processos.

Como é um webhook por dentro?

Todo webhook tem quatro peças:

1. URL de destino: o endereço público do seu sistema que vai receber o aviso, como https://www.suaempresa.com.br/webhooks/pagamentos.
2. Evento: o que dispara o aviso, como pagamento.aprovado. Você escolhe quais eventos quer receber.
3. Requisição POST com JSON: o aviso em si, com o tipo do evento, um identificador e os dados.
4. Assinatura ou segredo: um código enviado em um cabeçalho, calculado com um segredo que só você e o provedor conhecem. Serve para provar que o aviso é verdadeiro e não foi alterado.

Veja um exemplo fictício (cada provedor usa nomes e formatos próprios):

POST /webhooks/pagamentos HTTP/1.1
Host: www.suaempresa.com.br
Content-Type: application/json
X-Assinatura: sha256=9f2c41d8...e41b

{
  "id_evento": "evt_8f3a21",
  "tipo": "pagamento.aprovado",
  "criado_em": "2026-11-01T14:32:10-03:00",
  "dados": {
    "id_pagamento": "pg_550192",
    "pedido": "1042",
    "metodo": "pix",
    "status": "aprovado"
  }
}

O campo id_evento é o que permite saber se você já tratou este aviso. O cabeçalho de assinatura muda de nome conforme o serviço: na documentação da Stripe é Stripe-Signature, na do Mercado Pago é x-signature.

Como receber um webhook do jeito certo?

Receber é a parte que mais dá problema. Estas práticas aparecem, com variações, na documentação de quem envia webhooks, como a do GitHub e a do Mercado Pago:

1. Responda 2xx rápido. Um código como 200 diz "recebi". O GitHub pede resposta em até 10 segundos; o Mercado Pago espera 200 ou 201 e aguardava 22 segundos quando conferimos, em novembro de 2026. Cada provedor tem o seu prazo.
2. Processe depois. Receba, guarde e responda; faça o trabalho pesado em segundo plano, em uma fila. Se você demora, o provedor entende que falhou e reenvia.
3. Trate a idempotência. O mesmo aviso pode chegar duas vezes. Guarde os id_evento já tratados e ignore repetidos, senão o pedido é liberado (ou o e-mail enviado) em dobro.
4. Valide a assinatura. Sem isso, qualquer pessoa que conheça a URL pode mandar um "pagamento aprovado" falso. Confira a assinatura com o segredo antes de agir.
5. Use HTTPS. Os provedores costumam exigir, e protege os dados no caminho.
6. Registre log de tudo que chega, inclusive os recusados. É o que permite descobrir o que aconteceu quando algo some.
7. Espere reentregas e eventos fora de ordem. Se o seu sistema ficar fora do ar, vários provedores tentam de novo por algum tempo (a Stripe informa até três dias; a Meta, no WhatsApp, até sete). Alguns provedores avisam que os eventos podem chegar fora de ordem. Na dúvida, consulte o estado atual pela API.

Um esqueleto do fluxo, em pseudocódigo:

recebe o POST
se a assinatura for inválida -> responde 401 e para
se id_evento já foi tratado  -> responde 200 e para
grava o evento e coloca na fila
responde 200
(em segundo plano) libera o pedido, avisa o cliente, atualiza o CRM

Os avisos costumam trazer dados de pessoas, o que entra na LGPD: guarde só o necessário e proteja os logs. Isto é informação geral, não orientação jurídica.

Como testar um webhook antes de ligar de verdade?

Antes de apontar o provedor para o sistema real, dá para ver o aviso chegando:

• webhook.site: gera uma URL única e mostra, em tempo real, cabeçalhos e corpo de cada requisição recebida. Funciona sem cadastro, e as URLs gratuitas expiram depois de uma semana.
• Pipedream: o gatilho HTTP cria uma URL e exibe cada requisição recebida em um inspetor.
• ngrok: abre uma URL pública temporária que aponta para o servidor no seu computador, útil para testar o código que você mesmo está escrevendo. A própria documentação da Stripe sugere esse tipo de túnel.
• Ambiente de testes do provedor: a maioria tem modo de teste e painel de entregas, com status de cada tentativa e botão de reenvio.

Depois do primeiro aviso funcionar, teste o que dá errado: mande o mesmo evento duas vezes, mande uma assinatura inválida e derrube o endpoint de propósito para ver a reentrega.

API, webhook ou consulta periódica: qual usar?

Os três se combinam. Um desenho comum: o webhook avisa que houve um pagamento, e o seu sistema confirma pela API os dados completos antes de liberar o pedido. É o que a documentação do Mercado Pago orienta para pagamentos.

Quando vale pedir ajuda?

Para um fluxo simples, ferramentas de automação sem código como o n8n têm um gatilho de webhook pronto (no n8n, o nó Webhook). Quando o volume cresce, o dinheiro está envolvido ou as regras são próprias, o endpoint vira parte do sistema e precisa de fila, log, assinatura e alerta de falha. É esse tipo de trabalho que fazemos em sistemas sob medida e integrações. Se o aviso nasce em um formulário do seu site, o diagnóstico gratuito mostra como ele está hoje. Para decidir entre planilha, software pronto e sistema próprio, veja sistema sob medida ou planilha.