Webhook para quem não é técnico: como funciona e como ler um exemplo

Quem passa por uma implementação de CRM cedo ou tarde ouve a frase: 'vamos ligar isso por webhook'. A palavra assusta, mas a ideia é simples e vale conhecer, porque é ela que faz o lead do formulário aparecer no funil sem que ninguém digite nada. Este guia explica o conceito com uma analogia, abre um exemplo completo com dados inventados e termina com um glossário para consultar quando a palavra voltar.

Todos os dados de exemplo abaixo são fictícios. A empresa se chama Loja Aurora, uma marcenaria inventada que recebe pedidos de orçamento pelo site e atende pelo WhatsApp.

O que é um webhook, em uma frase e uma analogia?

Webhook é o aviso que um sistema manda para outro, sozinho, no instante em que um evento acontece. Em vez de você perguntar toda hora 'chegou alguma coisa?', o sistema toca a campainha quando chega.

Pense numa encomenda. Você pode ir ao ponto de retirada todo dia perguntar se o pacote chegou, ou pode dar o seu endereço e esperar o entregador tocar. Perguntar toda hora gasta tempo e quase sempre dá a resposta 'ainda não'. A campainha só toca quando há o que entregar. Webhook é a campainha.

• Sem webhook: alguém abre o sistema de hora em hora, exporta uma planilha e copia os novos contatos para o CRM. O lead espera, e o erro de digitação é questão de tempo.
• Com webhook: o formulário é enviado e, em segundos, o lead já está na primeira etapa do funil, com origem e campanha anotadas.

O nome vem de 'web' (a internet) mais 'hook' (gancho): um gancho pendurado em um evento, que dispara uma ação em outro lugar. Na área técnica, a alternativa de perguntar de tempos em tempos se chama consulta periódica, ou polling.

Como um webhook funciona por dentro?

Por dentro, todo webhook tem quatro peças: o evento que dispara, o endereço que recebe, a mensagem enviada e a resposta de quem recebeu. Entender essas quatro já resolve a maior parte das conversas de integração.

1. 1
   Evento

   É o que dispara o aviso: formulário enviado, lead que mudou de etapa, venda marcada como ganha, pagamento confirmado. Cada sistema define quais eventos oferece.

2. 2
   Endereço de recebimento

   É uma URL, um link, que fica no sistema que vai receber. O sistema que avisa precisa saber esse endereço. Por isso ele deve ser tratado como senha: quem o conhece pode mandar dados para ele.

3. 3
   Mensagem

   Normalmente é uma requisição HTTP do tipo POST, com os dados no corpo em formato JSON, que é só texto organizado em pares de nome e valor. O exemplo da próxima seção mostra como fica.

4. 4
   Resposta

   Quem recebe devolve um código de status. 200 quer dizer 'recebi'. Qualquer outro, como 404 ou 500, é lido pelo sistema que avisou como falha.

O que acontece quando a resposta não é 200 depende de cada sistema. A documentação da Meta para os webhooks do WhatsApp, por exemplo, diz que, se o seu endereço responder outra coisa ou não puder ser alcançado, ela tenta de novo com frequência cada vez menor, por até 7 dias, e que essas novas tentativas podem gerar avisos repetidos. Por isso quem recebe deve responder 200 rápido e saber lidar com repetição. O roteiro para quando o dado não chega está em como testar um webhook.

Como é um webhook de verdade? Um lead em JSON, campo a campo

Um webhook de formulário é um bloco de texto com os dados do lead. Veja o que a Loja Aurora (fictícia) enviaria quando Marina, uma cliente inventada, pede orçamento de uma cozinha.

{
  "evento": "formulario_enviado",
  "enviado_em": "2026-10-21T14:32:08-03:00",
  "origem": {
    "pagina": "orcamento-cozinha",
    "utm_source": "instagram",
    "utm_campaign": "cozinhas-outubro"
  },
  "lead": {
    "nome": "Marina Souza",
    "telefone": "+5511999990000",
    "email": "marina@exemplo.com",
    "interesse": "Cozinha planejada",
    "aceitou_contato": true
  }
}

As chaves { } agrupam um conjunto de dados, os textos vão entre aspas e cada linha é um par de nome e valor, como "telefone": "+5511999990000". Lido linha a linha, o exemplo diz o seguinte.

Com esse bloco na mão, o sistema que recebe faz perguntas simples: esse telefone já existe? Se sim, atualiza e anota a nova origem. Se não, cria um lead novo na primeira etapa e avisa o vendedor da vez. Nada disso exige que alguém olhe a tela.

Webhook ou API: qual a diferença?

No webhook, o sistema de origem avisa quando algo acontece. Na API, quem quer o dado vai buscar, ou envia, quando decide. Um é aviso por evento; o outro é consulta sob demanda.

Na prática os dois trabalham juntos. O webhook diz 'o lead 4821 mudou de etapa'; a API busca os detalhes desse lead para completar outra ação. A página API, webhook e MCP Server do DataCrazy mostra como as duas portas aparecem num CRM conversacional.

Onde o webhook aparece na rotina de um CRM?

Em qualquer ponto onde um dado nasce fora do CRM ou precisa sair dele. Estes são os usos que mais aparecem nas implementações:

• Formulário do site: o lead cai no funil sem digitação. Veja como integrar o formulário do site ao CRM.
• Formulário de anúncio: o lead da campanha chega com a campanha anotada, como em leads do Facebook Ads no CRM.
• Venda ganha: o financeiro ou o sistema de pedidos recebe o aviso para emitir cobrança ou nota.
• Pagamento confirmado: o CRM move o card para a etapa de pós-venda.
• Alerta interno: lead de valor alto gera um aviso para o gestor.
• Ferramenta de automação no meio: o n8n recebe o webhook, trata o dado e entrega onde precisa, como em integração DataCrazy com n8n.

Segundo a página de planos do DataCrazy, em outubro de 2026, a quantidade de webhooks por plano é 3 no Starter, 15 no Essential, 80 no Pro e ilimitado no Business, e a API REST e o MCP Server aparecem a partir do Essential. Na implementação, cada ponto de entrada ou saída costuma ocupar um webhook, então vale listar as integrações antes de escolher o plano. A página qual plano do DataCrazy escolher ajuda nessa conta.

Que cuidados evitam que o webhook vire problema?

Seis cuidados cobrem quase tudo: endereço protegido, segredo de verificação, só o dado necessário, resposta rápida, tolerância a repetição e alguém olhando quando falha.

• Endereço protegido: use sempre https e não publique o endereço em lugar aberto.
• Segredo de verificação: muitos sistemas assinam o aviso ou mandam uma chave em um cabeçalho. Quem recebe confere e descarta o que não bate.
• Só o dado necessário: a LGPD traz entre seus princípios o da necessidade (art. 6º, inciso III): trate o mínimo para a finalidade. Se o CRM não usa o CPF, ele não precisa viajar no webhook.
• Resposta rápida: responda 200 assim que receber e processe depois. Tarefa demorada dentro da resposta causa estouro de tempo e reenvio.
• Tolerância a repetição: o mesmo aviso pode chegar duas vezes. Usar o telefone ou um código do evento como chave evita lead duplicado.
• Alguém que olha: todo fluxo precisa de um aviso quando falha e de uma pessoa que vê esse aviso.

Glossário rápido de webhook

Estas são as palavras que mais aparecem quando a conversa de integração começa, em linguagem de quem não programa.

1. Qual evento deve disparar o aviso? (ex.: formulário enviado)
2. De qual sistema ele sai e para qual sistema vai?
3. Quais campos precisam viajar? Só os que o destino usa.
4. Qual campo identifica a pessoa? (telefone com +55 e DDD, por exemplo)
5. O que fazer se o contato já existe? (atualizar ou ignorar)
6. Qual a primeira etapa do funil e quem recebe o lead?
7. Como o sistema prova que o aviso é legítimo? (segredo, cabeçalho)
8. O que acontece se o destino estiver fora do ar? (nova tentativa, fila, aviso)
9. Quem é avisado quando o fluxo falha, e por qual canal?
10. Onde fica registrado o que foi recebido, para conferir depois?