O que é webhook e como funciona

Dois sistemas precisam conversar: um formulário capta um lead e o CRM tem que saber na hora. Há duas formas de fazer isso. Ou o CRM fica perguntando "tem lead novo?" a cada minuto, ou o formulário simplesmente avisa quando alguém se cadastra. A segunda forma é o webhook — e ela é quase sempre a melhor: em vez de perguntar sem parar e desperdiçar requisições, a aplicação de origem empurra o dado no exato momento em que o evento acontece.

Neste artigo você vai entender o que é um webhook, como ele funciona por baixo dos panos, no que difere do polling e de uma API comum, e como recebê-lo com segurança.

O que é um webhook

Um webhook é uma requisição HTTP que uma aplicação dispara automaticamente para outra quando um evento acontece. Quem envia é a aplicação de origem (onde o evento ocorreu); quem recebe é a aplicação de destino, numa URL pública chamada de callback. O método usado é quase sempre o POST, e junto vai um payload — os dados do evento, normalmente em formato JSON.

A analogia mais útil é pensar no webhook como uma "API ao contrário". Numa API tradicional, você chama o servidor quando quer alguma informação. Com o webhook, é o servidor que chama você quando tem algo novo para contar. Por isso ele também é descrito como uma arquitetura orientada a eventos (event-driven): nada dispara sem que um evento aconteça primeiro.

Webhook vs. polling: avisar em vez de perguntar

Antes dos webhooks, a forma padrão de saber de uma novidade era o polling: sua aplicação chamava a API da outra repetidamente ("já tem pedido novo? e agora? e agora?"). O problema é óbvio — a maioria dessas perguntas volta vazia, gastando requisições e banda à toa, e ainda assim você só descobre a novidade no próximo ciclo, com atraso.

O webhook inverte a lógica: a origem só te procura quando o evento realmente acontece.

Isso não significa que webhook seja sempre superior. O polling ainda faz sentido quando a fonte não oferece webhook, ou quando você só precisa de uma sincronização em lote de tempos em tempos — um relatório diário, por exemplo, não exige tempo real.

Anatomia de um webhook

Toda entrega de webhook tem três partes. Entender cada uma é o que separa "funcionou por sorte" de "sei exatamente o que está chegando".

A URL de callback

É o endereço que recebe a requisição. Você cadastra essa URL na aplicação de origem e ela passa a enviar os eventos para lá. Costuma ser um endpoint dedicado, como https://seu-site.com.br/webhooks/leads. Precisa ser público (a origem tem que alcançá-lo pela internet) e, por segurança, servido sobre HTTPS.

O payload

É o conteúdo da requisição: os dados do evento, quase sempre em JSON. Um payload típico de "lead criado" se parece com isto:

{
  "event": "lead.created",
  "timestamp": "2026-04-01T10:30:00Z",
  "data": {
    "id": 12345,
    "email": "joao@empresa.com",
    "name": "João Silva",
    "source": "landing-page"
  }
}

Cada ferramenta define o formato do seu próprio payload — os campos acima são só um exemplo. O que muda pouco é a ideia: um objeto que diz qual evento ocorreu, quando e traz os dados relevantes.

A assinatura

Como a URL é pública, qualquer um poderia enviar um POST falso para ela. Para provar que a requisição veio mesmo da origem esperada, o webhook costuma trazer uma assinatura num header HTTP:

POST /webhooks/leads HTTP/1.1
Host: seu-site.com.br
Content-Type: application/json
X-Signature-256: sha256=8f3b2c9e...

Essa assinatura é um HMAC: um código calculado a partir do corpo da requisição e de um segredo que só a origem e você conhecem. É o que você usa para separar o legítimo do falso — assunto da próxima seção.

Segurança: validando a assinatura

O modelo é simples e robusto. Ao configurar o webhook, você e a origem combinam um segredo compartilhado. A cada disparo, a origem calcula o HMAC do payload usando esse segredo e envia o resultado no header. Do seu lado, você recalcula o HMAC com o mesmo segredo e o mesmo corpo — se os dois baterem, a requisição é autêntica.

import hmac, hashlib

segredo = b"seu-segredo-compartilhado"
payload = request.body                    # os bytes crus do corpo
assinatura = request.headers.get("X-Signature-256", "")

esperado = "sha256=" + hmac.new(segredo, payload, hashlib.sha256).hexdigest()

if hmac.compare_digest(esperado, assinatura):
    ...  # webhook legítimo: processe
else:
    ...  # descarte: origem não confiável

Dois detalhes importam. Primeiro: calcule o HMAC sobre o corpo cru (os bytes exatos que chegaram), não sobre o JSON já convertido em objeto — reserializar muda espaços e ordem de campos e quebra a comparação. Segundo: compare com uma função de tempo constante, como o hmac.compare_digest, e não com ==, para não abrir brecha a ataques de temporização. Cada ferramenta tem seu próprio header — o GitHub usa X-Hub-Signature-256, o Stripe usa Stripe-Signature —, mas a mecânica é sempre a mesma.

Onde os webhooks aparecem na prática

Praticamente toda plataforma séria oferece webhooks hoje. Alguns usos recorrentes:

O que todos têm em comum é a reação imediata: nenhum deles obriga alguém a ficar consultando um painel à espera de que algo mude.

Boas práticas ao receber webhooks

Receber webhook parece trivial — é só um endpoint que aceita POST —, mas alguns cuidados evitam dor de cabeça em produção:

• Responda 200 rápido. O remetente espera uma confirmação de recebimento em poucos segundos. Valide a assinatura, responda 200 e jogue o processamento pesado para uma fila ou um job assíncrono, em vez de segurar a conexão aberta.
• Prepare-se para reentregas. Se o seu endpoint falha ou demora, muitos serviços tentam reenviar o mesmo evento. Torne o processamento idempotente (use o ID do evento para não processar duas vezes o mesmo webhook).
• Registre tudo em log. Guarde o evento recebido, o resultado da validação e o desfecho. Sem log, depurar uma entrega que "sumiu" vira adivinhação.
• Valide sempre a assinatura. Um endpoint público sem verificação é um convite a payloads forjados.
• Teste antes de ir para produção. Serviços como o webhook.site geram uma URL temporária que mostra, em tempo real, exatamente o payload e os headers que a origem envia — ótimo para inspecionar o formato antes de escrever o código de recebimento.

Webhook, n8n e Mautic

Webhook e automação andam juntos. Quem monta fluxos com n8n e Mautic convive com webhook o tempo todo: é ele que faz o Mautic avisar o n8n no instante em que um lead se cadastra ou abre um e-mail, sem ninguém precisar ficar de olho na tela.

O padrão costuma ser este: o Mautic dispara um webhook para um nó de webhook do n8n; o n8n recebe o payload, aplica a lógica que você quiser (enriquecer o dado, consultar um score, chamar uma IA) e, se for o caso, chama de volta a API do Mautic para atualizar o contato ou entrar numa campanha. É exatamente essa combinação que a gente detalha no guia de automação com n8n e Mautic. Para ferramentas sem nó nativo, o mesmo raciocínio vale via APIs públicas.

Perguntas frequentes sobre webhooks

O que é um webhook?

É uma notificação automática que uma aplicação envia para outra quando um evento acontece. Na prática, é uma requisição HTTP POST com um payload (normalmente em JSON) disparada para uma URL que você cadastrou. Em vez de você ficar perguntando "já aconteceu?", a origem avisa no instante em que o evento ocorre.

Qual a diferença entre webhook e polling?

No polling, a sua aplicação pergunta à outra, de tempos em tempos, se houve novidade — o que gasta requisições à toa e adiciona atraso. No webhook, a origem só chama a sua URL quando o evento realmente acontece. Webhook é push (empurra); polling é pull (puxa).

Webhook é a mesma coisa que uma API?

Não exatamente. Uma API tradicional espera você chamá-la para responder; o webhook é a própria aplicação te chamando quando algo acontece. Muitas ferramentas oferecem os dois: você usa a API para consultar dados e o webhook para ser avisado de mudanças em tempo real.

Como garantir que um webhook é legítimo?

Use HTTPS na URL de callback e valide a assinatura. A maioria das ferramentas envia um header com um HMAC — um código gerado a partir do payload e de um segredo compartilhado. Sua aplicação recalcula esse código com o mesmo segredo e compara: se bater, a requisição veio mesmo da origem esperada; se não, descarte.

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

Boa parte dos serviços tenta reenviar o webhook algumas vezes quando não recebe uma resposta de sucesso (200). Por isso, valide a assinatura, responda 200 rápido e deixe o trabalho pesado para segundo plano. Registre cada recebimento em log para conseguir depurar entregas que falharam.

Conclusão

Webhook é uma das ideias mais simples e mais úteis da integração entre sistemas: em vez de perguntar sem parar se algo mudou, você deixa a aplicação de origem avisar no exato momento do evento. Isso reduz latência, economiza requisições e é a base de qualquer automação que precise reagir em tempo real.

Para começar, escolha um evento simples numa ferramenta que você já usa, aponte o webhook para uma URL de teste, confira o payload e só então parta para a integração real — sempre validando a assinatura. Para se aprofundar na parte de segurança, a documentação do GitHub sobre validação de webhooks é uma referência canônica de como conferir a assinatura HMAC na prática.