## glossário

O que é Webhook?

Um webhook é um mecanismo pelo qual um sistema notifica outro automaticamente quando um evento acontece. Em vez de o seu servidor ficar perguntando "já mudou alguma coisa?", ele registra uma URL e espera — quando o evento ocorre, o outro sistema envia uma requisição HTTP para essa URL com os dados.

Daí a descrição clássica: webhook é uma API ao contrário. Numa API tradicional você é quem chama; num webhook, você é quem é chamado.

Polling versus webhook

Sem webhook, a alternativa é polling: consultar a API de tempos em tempos para verificar mudanças. O custo disso é alto — se você consulta a cada minuto e o evento acontece uma vez por dia, 1.439 chamadas foram desperdiçadas, e ainda assim a notícia pode chegar com até um minuto de atraso.

O que chega no seu endpoint quando um pagamento é aprovado

POST /webhooks/pagamentos HTTP/1.1
Content-Type: application/json
X-Signature: sha256=9f86d081884c7d659a2f...

{
  "evento": "pagamento.aprovado",
  "id": "pay_8fk29dl",
  "valor": 14900,
  "moeda": "BRL",
  "criado_em": "2026-07-18T09:12:44Z"
}

Regras para receber webhooks com segurança

Sua URL de webhook é pública — qualquer um pode descobri-la e enviar dados falsos. Por isso, alguns cuidados não são opcionais:

Valide a assinatura. Provedores sérios assinam o corpo da requisição com um segredo compartilhado (HMAC). Recalcule o hash e compare antes de confiar em qualquer dado.
Responda rápido, processe depois. Devolva 200 em milissegundos e jogue o trabalho pesado numa fila. Provedores costumam considerar timeout como falha e reenviar.
Trate duplicatas. Reenvios acontecem. Use o ID do evento para garantir idempotência — processar o mesmo webhook duas vezes não pode cobrar o cliente duas vezes.
Nunca confie só no payload. Em operações sensíveis, consulte a API do provedor para confirmar o estado real antes de agir.
Exija HTTPS. Dados de eventos costumam conter informação sensível.

Onde webhooks são usados

Gateways de pagamento avisando que uma cobrança foi aprovada ou estornada. O GitHub disparando o pipeline de CI a cada push. Plataformas de e-mail informando que uma mensagem sofreu bounce. Ferramentas de automação como n8n, Zapier e Make funcionam quase inteiramente sobre webhooks — o assunto aparece de perto no artigo sobre ferramentas de automação com chatbots.

Testando em desenvolvimento

O desafio de desenvolver com webhooks é que localhost não é acessível pela internet. A solução usual é um túnel — ferramentas como ngrok ou Cloudflare Tunnel expõem sua máquina local numa URL pública temporária, permitindo receber os eventos reais durante o desenvolvimento.

## faq

Perguntas frequentes

Qual a diferença entre webhook e API?

A direção da chamada. Numa API você faz a requisição quando quer os dados. Num webhook, o servidor remoto faz a requisição para você quando o evento acontece. Webhooks são push; APIs tradicionais são pull.

O que fazer se meu servidor estiver fora do ar quando o webhook chegar?

A maioria dos provedores implementa retentativas com espera progressiva, tentando de novo por minutos ou horas. Ainda assim, é prudente registrar todos os eventos recebidos e oferecer um mecanismo de reconciliação que consulte a API do provedor para recuperar eventos perdidos.

Webhook precisa devolver algum conteúdo?

Não. Basta um código de status 2xx para confirmar o recebimento. O corpo da resposta costuma ser ignorado pelo provedor — o que importa é responder rápido e com status de sucesso.