# Webhooks

# Como funcionam e como configurar os Webhooks

<span style="white-space: pre-wrap;">Os </span>**Webhooks**<span style="white-space: pre-wrap;"> permitem receber automaticamente informações enviadas por ferramentas externas. O sistema gera uma URL própria e, sempre que uma landing page, formulário ou outra plataforma envia dados para esse endereço, essas informações podem ser utilizadas para criar ou atualizar leads.</span>

<span style="white-space: pre-wrap;">Como cada ferramenta pode enviar os dados em formatos diferentes, é necessário primeiro receber uma chamada de exemplo e depois realizar o </span>**mapeamento dos campos**.

---

##### **Navegação no Módulo**

[![webhoocks.gif](https://ajuda.apresenta.me/uploads/images/gallery/2026-09/webhoocks.gif)](https://ajuda.apresenta.me/uploads/images/gallery/2026-09/webhoocks.gif)

**Rotina:**<span style="white-space: pre-wrap;"> Configurações &gt; Integrações &gt; </span>**Webhooks**

Nesta tela é possível cadastrar, configurar e acompanhar os webhooks utilizados para receber informações externas.

---

##### **Criar o Webhook**

[![image.png](https://ajuda.apresenta.me/uploads/images/gallery/2026-09/scaled-1680-/BYSimage.png)](https://ajuda.apresenta.me/uploads/images/gallery/2026-09/BYSimage.png)

<span style="white-space: pre-wrap;">Clique em </span>**Cadastrar**<span style="white-space: pre-wrap;"> para criar um novo webhook.</span>

<table id="bkmrk-campodescri%C3%A7%C3%A3onome-d"><colgroup><col></col><col></col></colgroup><tbody><tr><th>Campo

</th><th>Descrição

</th></tr><tr><td>**Nome do Webhook**

</td><td>Nome utilizado para identificar de onde os dados serão recebidos, como o nome de uma landing page, formulário ou plataforma.

</td></tr><tr><td>**URL para acessar o webhook**

</td><td>Endereço gerado automaticamente pelo sistema para receber os dados externos. A URL é disponibilizada depois que o cadastro é gravado.

</td></tr></tbody></table>

Após preencher o nome, grave o webhook.

Em seguida, copie a URL gerada e informe esse endereço na ferramenta que enviará os dados.

---

##### **Fazer um envio de teste**

Antes de configurar o mapeamento, o sistema precisa receber pelo menos uma chamada para identificar a estrutura dos dados enviados pela ferramenta externa.

Configure a URL do webhook na plataforma de origem e realize um envio de teste, como:

- preencher um formulário;
- enviar uma landing page;
- executar uma automação;
- disparar manualmente uma chamada pela ferramenta integrada.

Depois desse envio, o sistema passa a conhecer os campos disponíveis para o mapeamento.

<p class="callout info">Um webhook recém-criado ainda não possui o mapeamento necessário para criar os leads corretamente. O primeiro envio serve como exemplo para que o sistema identifique quais informações estão sendo recebidas.</p>

---

##### **Gravar o próximo recebimento**

<span style="white-space: pre-wrap;">Quando for necessário capturar novamente a estrutura enviada pela ferramenta externa, utilize a opção </span>**Gravar próximo recebimento**.

<table id="bkmrk-op%C3%A7%C3%A3odescri%C3%A7%C3%A3ogravar"><colgroup><col></col><col></col></colgroup><tbody><tr><th>Opção

</th><th>Descrição

</th></tr><tr><td>**Gravar próximo recebimento**

</td><td>Faz com que a próxima chamada recebida seja armazenada como exemplo para configuração do webhook, sem ser utilizada normalmente para criar um registro.

</td></tr></tbody></table>

Esse recurso é útil quando a plataforma altera o formato enviado ou quando é necessário refazer o mapeamento utilizando um novo exemplo.

---

##### **Mapear os campos**

[![image.png](https://ajuda.apresenta.me/uploads/images/gallery/2026-09/scaled-1680-/XATimage.png)](https://ajuda.apresenta.me/uploads/images/gallery/2026-09/XATimage.png)

Depois que uma chamada de exemplo for recebida, os campos enviados passam a ficar disponíveis para seleção.

As informações podem aparecer acompanhadas do valor recebido, facilitando a identificação de cada campo.

<table id="bkmrk-campodescri%C3%A7%C3%A3onomede"><colgroup><col></col><col style="width: 689px;"></col></colgroup><tbody><tr><th>Campo

</th><th>Descrição

</th></tr><tr><td>**Nome**

</td><td>Define qual informação recebida corresponde ao nome do contato. Campo obrigatório.

</td></tr><tr><td>**E-mail**

</td><td>Define qual informação corresponde ao endereço de e-mail.

</td></tr><tr><td>**Fone**

</td><td>Define qual informação corresponde ao telefone do contato.

</td></tr><tr><td>**Origem**

</td><td>Define a origem do lead. Pode utilizar o código ou o nome da origem.

</td></tr><tr><td>**Detalhes da origem**

</td><td>Armazena informações complementares relacionadas à origem.

</td></tr><tr><td>**Mensagem**

</td><td>Define qual conteúdo recebido será utilizado como mensagem do lead.

</td></tr><tr><td>**Observações**

</td><td>Permite armazenar informações adicionais recebidas na chamada.

</td></tr><tr><td>**Campanha AD**

</td><td>Relaciona o lead às informações da campanha correspondente.

</td></tr><tr><td>**ID remoto**

</td><td>Armazena um identificador externo enviado pela plataforma.

</td></tr><tr><td>**ID lead remoto**

</td><td>Armazena o identificador do lead na plataforma de origem.

</td></tr><tr><td>**ID**

</td><td>Pode ser utilizado para identificar um lead existente e atualizá-lo em vez de gerar um novo registro.

</td></tr></tbody></table>

<p class="callout info">Ao realizar o mapeamento, confira também o valor apresentado junto ao nome do campo. Isso ajuda a garantir que telefone, e-mail, nome e demais informações sejam relacionados corretamente.</p>

---

##### **Configurar a origem recebida**

<span style="white-space: pre-wrap;">O campo </span>**Origem**<span style="white-space: pre-wrap;"> pode utilizar tanto o código quanto o nome da origem enviada pela ferramenta externa.</span>

Caso a origem informada não exista no sistema, ela pode ser criada automaticamente a partir do valor recebido.

<table id="bkmrk-situa%C3%A7%C3%A3ocomportament"><colgroup><col></col><col style="width: 663px;"></col></colgroup><tbody><tr><th>Situação

</th><th>Comportamento

</th></tr><tr><td>**Origem já cadastrada**

</td><td>O lead é relacionado à origem correspondente.

</td></tr><tr><td>**Origem não cadastrada**

</td><td>O sistema cria a origem utilizando a informação recebida.

</td></tr></tbody></table>

Isso permite que os contatos já entrem classificados conforme a plataforma ou campanha responsável pelo envio.

---

##### **Definir valores padrão**

[![image.png](https://ajuda.apresenta.me/uploads/images/gallery/2026-09/scaled-1680-/B2oimage.png)](https://ajuda.apresenta.me/uploads/images/gallery/2026-09/B2oimage.png)

Os valores padrão são utilizados quando determinada informação não é enviada pela ferramenta externa.

<table id="bkmrk-campodescri%C3%A7%C3%A3ofinali"><colgroup><col></col><col style="width: 693px;"></col></colgroup><tbody><tr><th>Campo

</th><th>Descrição

</th></tr><tr><td>**Finalidade**

</td><td>Define uma finalidade padrão para os leads recebidos.

</td></tr><tr><td>**Origem**

</td><td>Define uma origem padrão quando ela não estiver presente nos dados recebidos.

</td></tr><tr><td>**Detalhes da origem**

</td><td>Preenche automaticamente uma informação complementar sobre a origem.

</td></tr><tr><td>**Observações**

</td><td>Adiciona uma observação padrão ao lead.

</td></tr><tr><td>**Campanha AD**

</td><td>Define uma campanha padrão quando essa informação não vier na chamada.

</td></tr></tbody></table>

<span style="white-space: pre-wrap;">Por exemplo, uma ferramenta pode enviar apenas </span>**nome e telefone**, enquanto o webhook complementa automaticamente o lead com finalidade e origem.

---

##### **Evitar duplicidade e atualizar leads**

<span style="white-space: pre-wrap;">O mapeamento do campo </span>**ID**<span style="white-space: pre-wrap;"> pode ser utilizado quando a ferramenta externa mantém um identificador fixo para cada contato.</span>

<table id="bkmrk-situa%C3%A7%C3%A3ocomportament-1"><colgroup><col></col><col style="width: 638px;"></col></colgroup><tbody><tr><th>Situação

</th><th>Comportamento

</th></tr><tr><td>**ID ainda não existente**

</td><td>Um novo lead pode ser criado.

</td></tr><tr><td>**ID já relacionado a um lead**

</td><td>O registro existente pode ser atualizado em vez de ser criado novamente.

</td></tr></tbody></table>

Esse comportamento é importante quando a plataforma de origem envia atualizações posteriores sobre o mesmo interessado.

---

##### **Acompanhar os Webhooks**

A tela principal apresenta os webhooks cadastrados e o status de cada configuração.

<table id="bkmrk-statusdescri%C3%A7%C3%A3oaguar"><colgroup><col></col><col></col></colgroup><tbody><tr><th>Status

</th><th>Descrição

</th></tr><tr><td>**Aguardando mapeamento**

</td><td>O webhook já recebeu uma chamada, mas os campos ainda precisam ser configurados para que os dados sejam processados corretamente.

</td></tr><tr><td>**Não houve chamado para este webhook**

</td><td>Nenhuma informação foi recebida pela URL até o momento.

</td></tr></tbody></table>

Esses status ajudam a identificar em qual etapa está cada integração.

<span style="white-space: pre-wrap;">Se o webhook indicar que </span>**não houve chamado**, revise principalmente a configuração da URL na ferramenta de origem.

<span style="white-space: pre-wrap;">Se estiver </span>**aguardando mapeamento**, é necessário abrir o webhook e relacionar os campos recebidos.

---

##### **Consultar o histórico**

Cada webhook possui um histórico próprio para acompanhar os acontecimentos relacionados à integração.

<table id="bkmrk-recursodescri%C3%A7%C3%A3ohist"><colgroup><col></col><col style="width: 756px;"></col></colgroup><tbody><tr><th>Recurso

</th><th>Descrição

</th></tr><tr><td>**Histórico**

</td><td>Permite consultar registros relacionados ao funcionamento e às alterações realizadas no webhook.

</td></tr></tbody></table>

Esse recurso pode ajudar na conferência e identificação de problemas durante a configuração.

---

##### **Conferir se o Webhook funcionou**

Depois de concluir o mapeamento:

1. Realize um novo envio pela ferramenta de origem.
2. Aguarde o recebimento pelo webhook.
3. Acesse a listagem de leads.
4. Verifique se o contato foi criado ou atualizado.
5. Confira se os campos foram preenchidos corretamente.
6. Consulte o histórico do webhook caso seja necessário validar o processamento.

---

#### **Perguntas frequentes**

<span style="white-space: pre-wrap;">➜ </span>**A URL não aparece no cadastro. Por quê?**<span style="white-space: pre-wrap;"> A URL é gerada depois que o webhook é gravado. Salve o cadastro e acesse novamente para visualizar e copiar o endereço.</span>

<span style="white-space: pre-wrap;">➜ </span>**Por que preciso fazer um envio antes de mapear?**<span style="white-space: pre-wrap;"> Porque cada ferramenta pode enviar os dados em uma estrutura diferente. O sistema utiliza uma chamada recebida como exemplo para apresentar os campos disponíveis para o mapeamento.</span>

<span style="white-space: pre-wrap;">➜ </span>**O webhook está como "Aguardando mapeamento". O que significa?**<span style="white-space: pre-wrap;"> Significa que o sistema já recebeu informações, mas ainda é necessário definir qual dado corresponde ao nome, telefone, e-mail e demais campos do lead.</span>

<span style="white-space: pre-wrap;">➜ </span>**O status informa que não houve chamado para o webhook. O que devo verificar?**<span style="white-space: pre-wrap;"> Confira se a URL foi informada corretamente na ferramenta externa e se ela realmente realizou o envio.</span>

<span style="white-space: pre-wrap;">➜ </span>**A origem precisa estar cadastrada antes?**<span style="white-space: pre-wrap;"> Não necessariamente. Quando a origem recebida não existir, o sistema pode criá-la automaticamente utilizando a informação enviada pela integração.</span>

<span style="white-space: pre-wrap;">➜ </span>**O mesmo contato pode entrar mais de uma vez?**<span style="white-space: pre-wrap;"> O campo </span>**ID**<span style="white-space: pre-wrap;"> pode ser utilizado para identificar o mesmo registro. Quando o identificador já estiver relacionado a um lead, o sistema pode atualizar o registro existente em vez de criar outro.</span>

<span style="white-space: pre-wrap;">➜ </span>**Posso cadastrar vários Webhooks?**<span style="white-space: pre-wrap;"> Sim. É possível criar diferentes webhooks para landing pages, formulários ou plataformas distintas.</span>

<span style="white-space: pre-wrap;">➜ </span>**Para que serve a opção Gravar próximo recebimento?**<span style="white-space: pre-wrap;"> Ela permite capturar uma nova chamada de exemplo para revisar ou refazer o mapeamento dos campos.</span>

<span style="white-space: pre-wrap;">➜ </span>**Qual é a diferença entre Webhook e Enviador de Leads?**<span style="white-space: pre-wrap;"> O </span>**Webhook recebe dados**<span style="white-space: pre-wrap;"> enviados por ferramentas externas para o sistema. O </span>**Enviador de Leads faz o caminho contrário**, enviando os dados dos leads do sistema para uma plataforma externa.