Webhook: o que é, como funciona e como validar a assinatura

Quando um evento acontece num sistema, ele pode avisar outro sistema na hora, sem esperar a pergunta: esse aviso automático é o webhook. Tecnicamente, é uma requisição HTTP POST, com os dados do evento em JSON, enviada para uma URL que você cadastrou.

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 como o webhook funciona por baixo dos panos, no que difere do polling e de uma API comum e como testá-lo e 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?"). A maioria dessas perguntas volta vazia e gasta requisições e banda à toa. Mesmo 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.

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.

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, e os campos acima são só um exemplo. A ideia muda pouco: 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. Ela separa o legítimo do falso, assunto da próxima seção.

Segurança: validando a assinatura

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, e se os dois baterem a requisição é autêntica. A função abaixo segue a da documentação do GitHub (o HTTPException vem do FastAPI):

import hashlib
import hmac

def verify_signature(payload_body, secret_token, signature_header):
    if not signature_header:
        raise HTTPException(status_code=403, detail="x-hub-signature-256 header is missing!")
    hash_object = hmac.new(secret_token.encode('utf-8'), msg=payload_body, digestmod=hashlib.sha256)
    expected_signature = "sha256=" + hash_object.hexdigest()
    if not hmac.compare_digest(expected_signature, signature_header):
        raise HTTPException(status_code=403, detail="Request signatures didn't match!")

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.

Como testar e proteger um webhook

No Stripe, stripe listen --forward-to localhost:4242/webhook encaminha os eventos para a sua máquina, e stripe trigger payment_intent.succeeded dispara um evento de teste. Para conferir o seu HMAC, o GitHub publica um par pronto: o segredo It's a Secret to Everybody com o payload Hello, World! precisa dar sha256=757107ea0eb2509fc211221cce984b8a37570b6d7586c22c46f4379c8b043e17.

Prepare também o endpoint para eventos repetidos:

Grave o ID de cada entrega processada e ignore o que já estiver gravado: isso é idempotência. Contra replay (o reenvio de uma entrega interceptada), o Stripe põe um timestamp dentro da assinatura, e as bibliotecas dele recusam por padrão diferenças acima de 5 minutos.

Onde os webhooks aparecem na prática

Quase toda plataforma oferece webhooks hoje. Alguns usos recorrentes:

Boas práticas ao receber webhooks

Receber webhook parece trivial, já que é 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, o payload e os headers que a origem envia. Assim você vê 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.

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. Tecnicamente, é 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 troca a pergunta repetida pelo aviso no 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 e 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 ir mais fundo, a documentação do GitHub sobre validação de webhooks traz a mesma função de verificação em Python, Ruby e JavaScript.