Integrar leads com CRM: campos, UTM e webhook

Para integrar leads com CRM sem perder dados, envie cada conversão com uma chave externa única, dados de contato, respostas, qualificação e origem; depois, busque o contato antes de criar ou atualizar registros. A escolha entre integração nativa, Zapier, Make e webhook próprio depende do volume, das regras necessárias e de quem vai monitorar falhas.

É melhor usar integração nativa, Zapier, Make ou webhook?

Use integração nativa quando o mapeamento disponível já atende ao processo comercial. Escolha Zapier ou Make quando precisar transformar dados e combinar aplicativos sem manter código; prefira webhook próprio quando idempotência, regras complexas, volume ou observabilidade justificarem uma camada técnica dedicada.

Zapier, Make, n8n e Pluga ocupam a camada intermediária entre a origem e CRMs como HubSpot, Pipedrive, RD Station CRM, Salesforce ou Kommo. Essa camada recebe o evento, normaliza os campos, procura registros existentes e decide se deve criar um contato, atualizar um lead ou abrir um negócio. O nome da ferramenta importa menos do que a existência dessas decisões explícitas.

A integração nativa não é automaticamente a opção mais segura. Se ela não expõe o identificador da submissão, não preserva UTMs ou não permite inspecionar falhas, você pode ter uma conexão simples e ainda perder atribuição ou criar duplicidades. Já o webhook próprio não serve para uma operação sem alguém responsável por alertas, credenciais, filas e mudanças na API REST do CRM.

Quais campos precisam chegar ao CRM?

Mapeie quatro grupos: identidade do evento, contato, qualificação e atribuição. O mínimo não é apenas nome, e-mail e telefone: o CRM precisa receber contexto suficiente para deduplicar, priorizar e explicar de onde veio cada lead.

Contrato de dados para formulário ou quiz

• Evento: submission_id, data e hora, nome do formulário ou quiz, versão e URL em que a conversão ocorreu.
• Contato: nome, sobrenome quando disponível, e-mail, telefone normalizado, empresa e consentimento.
• Qualificação: todas as respostas, score, resultado, tags, segmento, produto de interesse e observações.
• Atribuição: first-touch UTM, last-touch UTM, landing_url, referrer, gclid, fbclid e identificadores de campanha, conjunto e anúncio quando fornecidos pela plataforma.
• Operação comercial: pipeline, etapa inicial, responsável, origem comercial e regra para abrir ou não um negócio.
• Controle técnico: status de processamento, tentativas, mensagem de erro, data do último envio e identificador criado no CRM.

Campos que parecem equivalentes nem sempre casam. Nome completo pode precisar ser separado em nome e sobrenome. Telefone deve ser normalizado com o código do país, sem perder o valor original recebido. Respostas de múltipla escolha precisam ser convertidas para opções aceitas pelo CRM; datas, booleanos e textos longos também devem respeitar o tipo do campo de destino.

Não abra uma oportunidade para toda submissão por padrão. Um contato pode ser criado ou atualizado para manter o histórico, enquanto o negócio só nasce quando uma regra comercial for atendida: score, resultado, intenção declarada, região atendida ou ausência de uma oportunidade ativa equivalente. Essa separação evita transformar curiosidade, teste interno e reenvio em pipeline artificial.

Para leads de quiz, envie respostas e score como campos personalizados ou como uma atividade associada ao contato. O campo personalizado ajuda na segmentação; a atividade preserva o contexto de cada conversão. Se você ainda está desenhando essas perguntas, use o guia de perguntas para quiz por nicho antes de fechar o mapeamento.

Como preservar UTMs e a origem original?

Capture a origem no primeiro acesso, persista esses valores durante a navegação e recupere-os no envio do formulário ou quiz. Depois, mantenha campos separados para first touch e last touch, nunca sobrescreva o first touch e registre cada nova conversão no histórico.

Na documentação atual do Google Analytics, utm_source, utm_medium, utm_campaign, utm_term e utm_content alimentam dimensões distintas de origem, mídia, campanha, termo e conteúdo do anúncio. Se qualquer UTM estiver presente e GCLID ou DCLID não puder ser usado, o Google Analytics recomenda preencher todos os parâmetros relevantes; o que faltar pode aparecer como “(not set)”. Por isso, não compacte toda a atribuição em um único campo de texto.

No primeiro acesso ao site, leia UTMs, landing_url, referrer, gclid e fbclid. Se toda a jornada ocorre na mesma origem, você pode persistir a primeira fotografia no localStorage; se ela atravessa subdomínios, use um cookie próprio configurado para o domínio pai e envie somente as páginas necessárias por HTTPS. Defina e documente a duração conforme o ciclo comercial e as regras de consentimento. Quando o armazenamento estiver bloqueado, indisponível ou não autorizado, envie apenas a origem disponível na conversão atual, mantenha o first touch vazio e marque-o como não capturado, sem inferir valores. Em cada página, preserve a fotografia inicial; no envio, recupere-a mesmo que a URL atual já não contenha parâmetros.

• First touch: capture UTMs, landing_url e referrer no primeiro acesso, persista-os durante a navegação e só preencha os campos do CRM quando estiverem vazios.
• Last touch: leia a origem da conversão atual e atualize esses campos a cada nova conversão válida sem alterar o first touch.
• Origem comercial: use uma classificação controlada, como mídia paga, indicação, parceiro ou orgânico, conforme a regra da operação.
• Fonte de criação: registre se o contato nasceu por integração, importação, formulário, API ou criação manual.
• Histórico: salve cada submissão como atividade ou registro associado, com suas próprias UTMs e respostas.

O HubSpot esclarece em sua documentação que Fonte do registro indica o processo que criou o registro, enquanto Detalhes da fonte pode identificar o formulário específico. Isso não equivale à fonte de tráfego. Se você usar Fonte do registro como se fosse utm_source, a análise comercial mistura mecanismo de criação com aquisição.

Em formulário próprio, o script deve recuperar a fotografia persistida do first touch e combinar esses dados com a origem da conversão atual antes de enviar a submissão. Em Meta Lead Ads, o fluxo é diferente: segundo a documentação da Meta, o webhook entrega metadados como leadgen_id, page_id, form_id, adgroup_id, ad_id e created_time; as respostas do lead são buscadas depois usando o leadgen_id. Logo, não presuma que um formulário nativo terá as mesmas UTMs capturadas em uma página própria.

O CRM deve guardar esses identificadores mesmo quando o time comercial não os utiliza na tela. Eles permitem reconciliar eventos, investigar atribuição e devolver resultados de venda às plataformas. A implementação desse retorno é outro problema; veja o processo específico em conversões offline no Google Ads sem misturá-lo com o transporte inicial do lead tratado aqui.

Como impedir contatos e negócios duplicados?

Use submission_id ou leadgen_id como chave externa do evento. Para localizar o contato, use o e-mail normalizado como identificador primário e o telefone normalizado como alternativa quando o e-mail estiver ausente. Se o e-mail apontar para um contato e o telefone para outro, não una nem atualize automaticamente: marque o evento como conflito e envie-o para revisão.

Contato, conversão e oportunidade devem ser tratados como entidades diferentes. Uma pessoa pode converter novamente sem virar outro contato ou ganhar automaticamente outro negócio. Telefones compartilhados também não devem provocar fusão automática entre contatos diferentes.

1. Receba o evento, valide a chave externa e grave o payload em uma caixa de entrada persistente com restrição de unicidade para submission_id ou leadgen_id antes de confirmar o recebimento.
2. Crie checkpoints separados para contato, conversão, negócio, notificação e demais efeitos. Cada efeito deve ter uma chave estável derivada do evento e guardar os status pendente, concluído ou falhou, além do identificador retornado pelo destino.
3. Normalize e-mail e telefone. Procure primeiro pelo e-mail; use o telefone como alternativa quando o e-mail estiver ausente. Se os dois identificadores apontarem para contatos diferentes, interrompa a atualização automática e envie o conflito para revisão.
4. Antes de criar ou atualizar o contato, consulte o checkpoint e o CRM. Use upsert ou um campo externo pesquisável para localizar um efeito já concluído; depois, grave o identificador do contato no checkpoint.
5. Antes de registrar a conversão, procure a chave própria dessa atividade no destino. Se ela já existir, apenas recupere o identificador; se não existir, crie a atividade com essa chave e marque a etapa como concluída.
6. Aplique a mesma regra ao negócio: consulte uma chave estável ou uma oportunidade compatível antes de atualizar, criar ou decidir que nenhuma oportunidade deve nascer.
7. Em uma repetição, retome a partir do primeiro checkpoint incompleto e consulte o destino antes de refazer o efeito. Só marque o evento inteiro como processado quando todas as etapas obrigatórias estiverem concluídas.

Esse desenho reduz duplicidades em falhas parciais porque o retry não recomeça todo o fluxo. A garantia depende, porém, de cada destino aceitar uma chave idempotente ou permitir pesquisar a chave externa antes da criação. Se o CRM não oferece nenhum dos dois, uma falha entre a criação remota e a gravação do checkpoint deixa uma janela de duplicidade; nesse caso, mantenha o evento para reconciliação e revisão antes do replay.

A operação conhecida como upsert ou find or create ajuda no contato, mas não basta sozinha. Atividades, negócios, notificações e distribuição de responsável precisam de chaves e checkpoints próprios. Assim, se o contato e a atividade forem criados, mas a abertura do negócio falhar, o reenvio consulta os efeitos anteriores e retoma somente a etapa pendente.

Deduplicar somente por e-mail cria uma fronteira frágil. Na documentação do eKyte, por exemplo, a verificação de contato no webhook ocorre apenas pelo e-mail; o modo create pode abrir nova tarefa para um contato existente, enquanto update altera a tarefa ativa mais recente. Isso mostra por que a regra do conector precisa ser conferida contra o comportamento comercial esperado, especialmente quando o e-mail falta ou o telefone é compartilhado.

Se a venda ocorre no WhatsApp, não use o número apenas como destino de mensagem. Normalize-o e mantenha a ligação entre contato, conversa e oportunidade. O guia de CRM para leads do WhatsApp detalha os requisitos comerciais dessa etapa.

Como testar a integração e recuperar falhas?

Teste o fluxo com casos normais, incompletos, repetidos e fora do padrão antes de publicar. Depois, mantenha uma cópia das submissões, status de processamento, alertas, retry com backoff, fila de erros, replay manual e reconciliação entre origem e CRM.

Checklist de homologação

• Lead completo com todas as UTMs e respostas.
• E-mail ausente e telefone válido.
• Telefone inválido ou em formato inesperado.
• Mesmo evento reenviado com a mesma chave externa.
• Mesmo contato fazendo uma nova conversão.
• E-mail e telefone apontando para contatos diferentes.
• UTM ausente e campos opcionais vazios.
• Acentos, caracteres especiais, respostas longas e múltipla escolha.
• CRM indisponível, credencial expirada ou resposta de rate limit.
• Pico de volume e processamento fora de ordem.
• Criação de contato bem-sucedida, mas falha posterior ao abrir o negócio.

HTTP 200 indica ao emissor que o endpoint respondeu com sucesso, não que o evento foi armazenado com segurança ou que todo o fluxo comercial terminou. O Google considera bem-sucedido o teste do webhook de formulário de lead quando recebe HTTP 200 e classifica outra resposta como erro D. Se o seu endpoint devolver sucesso antes de gravar ou enfileirar o evento com segurança, o emissor pode encerrar o envio mesmo que o CRM falhe depois.

No Zapier, o Autoreplay tenta repetir uma etapa com erro até cinco vezes, nos intervalos de 5 minutos, 30 minutos, 1 hora, 3 horas e 6 horas, segundo a documentação do Zapier. Isso ajuda em indisponibilidades temporárias, mas não substitui idempotência: cada repetição precisa poder ocorrer sem duplicar registros.

No Make, webhooks são limitados a 300 requisições recebidas a cada 10 segundos; acima disso, o serviço responde com HTTP 429. A documentação também informa que webhooks instantâneos são processados em paralelo por padrão e oferece a opção Process data in order quando a ordem precisa ser mantida. Se uma atualização depende da anterior, configure a ordem ou trate versões e horários no seu fluxo.

Como calcular o custo da integração?

Calcule o custo pelo número de ações executadas por lead em cada caminho possível. Separe pelo menos contato novo, contato existente e retry após falha parcial, porque eles podem consumir quantidades diferentes de tarefas ou créditos.

Segundo a explicação de preços do Zapier, cada ação bem-sucedida em outro aplicativo normalmente consome uma tarefa, enquanto gatilhos, filtros, paths, erros e interrupções não consomem tarefas. O plano gratuito inclui 100 tarefas mensais; o Professional começa em US$ 19,99 por mês com 750 tarefas e o Team em US$ 69 por mês com 2.000 tarefas, quando faturados anualmente.

No Make, a maioria das ações consome um crédito, incluindo leitura, busca, criação, atualização, exclusão e transformação de dados, conforme a página oficial de preços. Um cenário visualmente curto pode consumir vários créditos por lead se procurar o contato, transformar campos, criar um registro e atualizar outro. Conte cada módulo realmente executado nos caminhos de contato novo, contato existente e erro.

Exemplo de consumo por caminho

Considere um fluxo hipotético que busca o contato, cria ou atualiza o cadastro, registra a conversão, abre negócio quando necessário, salva um backup e envia uma notificação. No Make, considere também um módulo separado para transformar os campos. O cálculo abaixo é do fluxo descrito, não um benchmark das plataformas.

Sem checkpoints, o caminho de retry pode repetir busca, criação ou atualização e atividade, elevando o consumo e o risco de duplicidade. No Zapier, a falha em si não consome tarefa segundo a explicação oficial, mas as ações bem-sucedidas repetidas consomem. No Make, confira o histórico do cenário para somar os módulos efetivamente cobrados na tentativa que falhou.

• Desenhe cada caminho possível do fluxo, inclusive contato existente e falha parcial.
• Conte buscas, criações, atualizações, atividades, negócios, notificações e backups.
• Multiplique o consumo de cada caminho pelo volume esperado daquele tipo de evento.
• Inclua retries e reprocessamentos na margem operacional.
• Compare o custo da automação com o custo técnico de manter webhook, fila, banco e monitoramento próprios.

Integração própria não elimina custo; ela troca tarefas ou créditos por desenvolvimento e operação. Zapier ou Make deixam de servir quando o preço, os limites ou a falta de controle superam a conveniência. A integração nativa deixa de servir quando não transporta os dados que sua atribuição e seu time comercial realmente usam.