Webhooks
Como funcionam e como configurar os Webhooks
Os Webhooks 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.
Como cada ferramenta pode enviar os dados em formatos diferentes, é necessário primeiro receber uma chamada de exemplo e depois realizar o mapeamento dos campos.
Navegação no Módulo
Rotina: Configurações > Integrações > Webhooks
Nesta tela é possível cadastrar, configurar e acompanhar os webhooks utilizados para receber informações externas.
Criar o Webhook
Clique em Cadastrar para criar um novo webhook.
Campo | Descrição |
|---|---|
Nome do Webhook | Nome utilizado para identificar de onde os dados serão recebidos, como o nome de uma landing page, formulário ou plataforma. |
URL para acessar o webhook | Endereço gerado automaticamente pelo sistema para receber os dados externos. A URL é disponibilizada depois que o cadastro é gravado. |
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.
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.
Gravar o próximo recebimento
Quando for necessário capturar novamente a estrutura enviada pela ferramenta externa, utilize a opção Gravar próximo recebimento.
Opção | Descrição |
|---|---|
Gravar próximo recebimento | 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. |
Esse recurso é útil quando a plataforma altera o formato enviado ou quando é necessário refazer o mapeamento utilizando um novo exemplo.
Mapear os campos
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.
Campo | Descrição |
|---|---|
Nome | Define qual informação recebida corresponde ao nome do contato. Campo obrigatório. |
Define qual informação corresponde ao endereço de e-mail. | |
Fone | Define qual informação corresponde ao telefone do contato. |
Origem | Define a origem do lead. Pode utilizar o código ou o nome da origem. |
Detalhes da origem | Armazena informações complementares relacionadas à origem. |
Mensagem | Define qual conteúdo recebido será utilizado como mensagem do lead. |
Observações | Permite armazenar informações adicionais recebidas na chamada. |
Campanha AD | Relaciona o lead às informações da campanha correspondente. |
ID remoto | Armazena um identificador externo enviado pela plataforma. |
ID lead remoto | Armazena o identificador do lead na plataforma de origem. |
ID | Pode ser utilizado para identificar um lead existente e atualizá-lo em vez de gerar um novo registro. |
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.
Configurar a origem recebida
O campo Origem pode utilizar tanto o código quanto o nome da origem enviada pela ferramenta externa.
Caso a origem informada não exista no sistema, ela pode ser criada automaticamente a partir do valor recebido.
Situação | Comportamento |
|---|---|
Origem já cadastrada | O lead é relacionado à origem correspondente. |
Origem não cadastrada | O sistema cria a origem utilizando a informação recebida. |
Isso permite que os contatos já entrem classificados conforme a plataforma ou campanha responsável pelo envio.
Definir valores padrão
Os valores padrão são utilizados quando determinada informação não é enviada pela ferramenta externa.
Campo | Descrição |
|---|---|
Finalidade | Define uma finalidade padrão para os leads recebidos. |
Origem | Define uma origem padrão quando ela não estiver presente nos dados recebidos. |
Detalhes da origem | Preenche automaticamente uma informação complementar sobre a origem. |
Observações | Adiciona uma observação padrão ao lead. |
Campanha AD | Define uma campanha padrão quando essa informação não vier na chamada. |
Por exemplo, uma ferramenta pode enviar apenas nome e telefone, enquanto o webhook complementa automaticamente o lead com finalidade e origem.
Evitar duplicidade e atualizar leads
O mapeamento do campo ID pode ser utilizado quando a ferramenta externa mantém um identificador fixo para cada contato.
Situação | Comportamento |
|---|---|
ID ainda não existente | Um novo lead pode ser criado. |
ID já relacionado a um lead | O registro existente pode ser atualizado em vez de ser criado novamente. |
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.
Status | Descrição |
|---|---|
Aguardando mapeamento | O webhook já recebeu uma chamada, mas os campos ainda precisam ser configurados para que os dados sejam processados corretamente. |
Não houve chamado para este webhook | Nenhuma informação foi recebida pela URL até o momento. |
Esses status ajudam a identificar em qual etapa está cada integração.
Se o webhook indicar que não houve chamado, revise principalmente a configuração da URL na ferramenta de origem.
Se estiver 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.
Recurso | Descrição |
|---|---|
Histórico | Permite consultar registros relacionados ao funcionamento e às alterações realizadas no webhook. |
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:
- Realize um novo envio pela ferramenta de origem.
- Aguarde o recebimento pelo webhook.
- Acesse a listagem de leads.
- Verifique se o contato foi criado ou atualizado.
- Confira se os campos foram preenchidos corretamente.
- Consulte o histórico do webhook caso seja necessário validar o processamento.
Perguntas frequentes
➜ A URL não aparece no cadastro. Por quê? A URL é gerada depois que o webhook é gravado. Salve o cadastro e acesse novamente para visualizar e copiar o endereço.
➜ Por que preciso fazer um envio antes de mapear? 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.
➜ O webhook está como "Aguardando mapeamento". O que significa? 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.
➜ O status informa que não houve chamado para o webhook. O que devo verificar? Confira se a URL foi informada corretamente na ferramenta externa e se ela realmente realizou o envio.
➜ A origem precisa estar cadastrada antes? Não necessariamente. Quando a origem recebida não existir, o sistema pode criá-la automaticamente utilizando a informação enviada pela integração.
➜ O mesmo contato pode entrar mais de uma vez? O campo ID 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.
➜ Posso cadastrar vários Webhooks? Sim. É possível criar diferentes webhooks para landing pages, formulários ou plataformas distintas.
➜ Para que serve a opção Gravar próximo recebimento? Ela permite capturar uma nova chamada de exemplo para revisar ou refazer o mapeamento dos campos.
➜ Qual é a diferença entre Webhook e Enviador de Leads? O Webhook recebe dados enviados por ferramentas externas para o sistema. O Enviador de Leads faz o caminho contrário, enviando os dados dos leads do sistema para uma plataforma externa.