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

> O que é webhook no CRM: é um aviso automático que um sistema envia a outro, como o site ao CRM, na hora em que algo acontece, sem ninguém pedir. Quando alguém preenche um formulário, por exemplo, o site manda os dados do lead para um endereço de recebimento e o CRM cria o contato em segundos. É a forma mais comum de ligar sistemas sem copiar e colar.

Página original: https://www.adprotecnologia.com.br/crm/blog/o-que-e-webhook
Autor: AD PRO Tecnologia. Publicado em 2026-10-21. Atualizado em 2026-11-07.

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. **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. **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. **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. **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](https://www.adprotecnologia.com.br/crm/blog/como-testar-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.

**Exemplo de corpo de webhook: lead de formulário (dados fictícios)**

```text
{
  "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.

**O que cada campo do exemplo diz e como o CRM costuma usá-lo**

| Campo | O que diz | Como o CRM usa |
| --- | --- | --- |
| evento | O que aconteceu: um formulário foi enviado | Decide qual fluxo rodar. Um mesmo endereço pode receber vários tipos de evento |
| enviado_em | Data e hora, com o fuso (-03:00 é o horário de Brasília) | Registra quando o lead chegou e calcula o tempo da primeira resposta |
| origem.pagina, utm_source, utm_campaign | De qual página e de qual campanha o lead veio | Grava a origem do lead, base de qualquer relatório de [origem do lead](https://www.adprotecnologia.com.br/crm/rastrear-origem-do-lead-no-crm) |
| lead.nome | Nome informado | Nome do contato no cadastro |
| lead.telefone | Telefone com código do país (+55) e DDD | Chave para achar contato repetido e abrir a conversa no WhatsApp |
| lead.email | E-mail informado | Dado de apoio; muitos negócios só pedem e-mail quando precisam |
| lead.interesse | O que a pessoa quer | Escolhe o pipeline ou o vendedor que atende esse assunto |
| lead.aceitou_contato | Se marcou o aceite no formulário | Registro de consentimento, ligado à [LGPD no CRM](https://www.adprotecnologia.com.br/crm/blog/lgpd-no-crm) |

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.

**Webhook e API lado a lado**

|  | Webhook | API |
| --- | --- | --- |
| Quem começa a conversa | O sistema onde o evento aconteceu | O sistema que precisa do dado |
| Quando acontece | No instante do evento | Quando alguém ou algo chama |
| Bom para | Reagir a algo novo: lead, mudança de etapa, pagamento | Consultar, criar ou atualizar um registro específico |
| Exemplo | 'Chegou um lead no formulário' | 'Me dê os dados do lead 4821' ou 'atualize este telefone' |
| Custo de operação | Baixo, só roda quando há evento | Depende de quantas chamadas se fazem |

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](https://www.adprotecnologia.com.br/crm/datacrazy-api-webhook-mcp) 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](https://www.adprotecnologia.com.br/crm/blog/integrar-formulario-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](https://www.adprotecnologia.com.br/crm/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](https://www.adprotecnologia.com.br/crm/integracao-datacrazy-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](https://www.adprotecnologia.com.br/crm/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.

> **Como a AD PRO trata webhook na implementação:** Na implementação, o que mais vemos é webhook configurado e ninguém sabendo o que ele faz seis meses depois. A AD PRO, parceira Premier e implementadora do DataCrazy, monta as integrações via webhook, API ou n8n e entrega um mapa de uma página: de onde vem o dado, para onde vai, qual campo é a chave e quem avisar se falhar.

## 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.

**Termos de webhook em português claro**

| Termo | Quer dizer |
| --- | --- |
| Payload | O conteúdo do aviso: o bloco de dados, como o JSON do exemplo |
| Endpoint ou URL do webhook | O endereço que recebe o aviso |
| POST | O tipo de requisição que leva dados dentro do corpo; é o mais usado em webhook |
| JSON | Formato de texto com pares de nome e valor, legível por pessoas e por sistemas |
| Cabeçalho (header) | Informações extras que vão junto, como o tipo de conteúdo e a chave de verificação |
| Status 200 | Resposta que significa 'recebi com sucesso' |
| Nova tentativa (retry) | Reenvio automático do aviso quando a resposta não foi 200 |
| Idempotência | Propriedade de receber o mesmo aviso duas vezes sem criar duplicidade |
| Segredo ou token | Chave que prova que o aviso veio de quem deveria |

**Checklist para levar à conversa de integração**

```text
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?
```

## Perguntas frequentes

### O que é webhook, em palavras simples?

É um aviso automático entre sistemas. Quando algo acontece em um deles, como um formulário enviado, ele manda os dados para um endereço do outro, sem ninguém pedir. É como a campainha da encomenda: você não precisa ir ver se chegou.

### Qual a diferença entre webhook e API?

No webhook, o sistema onde o evento aconteceu avisa quando ele ocorre. Na API, quem precisa do dado faz a chamada quando quiser, para buscar ou gravar algo. Muitas integrações usam as duas: o webhook avisa e a API completa os detalhes.

### Para que serve um webhook em um CRM?

Serve para o CRM receber ou emitir avisos sem digitação: lead de formulário que entra no funil, venda ganha que chega ao financeiro, pagamento confirmado que muda a etapa. Cada ponto de entrada ou saída costuma usar um webhook.

### Webhook é seguro?

Pode ser, se o endereço usar https, se houver uma chave de verificação e se só trafegarem os dados necessários. Um endereço aberto, sem verificação, aceita dado de qualquer um, e por isso a verificação é parte da montagem, não detalhe.

### Preciso saber programar para usar um webhook?

Não para entender nem para decidir o que ligar. Para montar, é preciso configurar o endereço, os campos e a verificação, e muita gente usa uma ferramenta de automação como o n8n para isso. Na AD PRO, essa montagem é parte da implementação.

### O DataCrazy tem webhook?

Sim. Segundo a página de planos, em outubro de 2026, o Starter traz 3 webhooks, o Essential 15, o Pro 80 e o Business, ilimitado. A API REST e o MCP Server aparecem a partir do Essential. Integrações com outros sistemas são montadas em cima dessas portas.

## Fontes

- [DataCrazy, página inicial](/ir/datacrazy?de=o-que-e-webhook&pos=texto), conferido em 2026-10-21
- [DataCrazy, planos e valores](/ir/datacrazy?de=o-que-e-webhook&pos=texto&p=%2Fplanos), conferido em 2026-10-21
- [Meta for Developers, webhooks do WhatsApp (resposta 200 e novas tentativas)](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview/), conferido em 2026-10-21
- [Planalto, Lei 13.709/2018 (LGPD), princípios do art. 6º](https://www.planalto.gov.br/ccivil_03/_ato2015-2018/2018/lei/l13709.htm), conferido em 2026-10-21
- [IETF, RFC 9110 (semântica do HTTP: métodos e códigos de status)](https://www.rfc-editor.org/rfc/rfc9110), conferido em 2026-10-21

---

AD PRO Tecnologia LTDA, CNPJ 68.425.611/0001-15, São Paulo/SP. Atendimento on-line para todo o Brasil. Diagnóstico comercial gratuito de 30 minutos: https://www.adprotecnologia.com.br/#agendar. WhatsApp +55 11 98604-5939. Fatos e preços publicados: https://www.adprotecnologia.com.br/fatos