Rastreamento de cliques em links do HubSpot: escrever cliques na timeline do deal

Se a sua equipe de vendas vive no HubSpot mas o rastreamento de campanhas vive em uma ferramenta de links curtos, você tem duas timelines que nunca se comunicam. O marketer vê cliques; o AE vê estágios do deal. Ninguém vê a conexão entre eles. Este guia explica como conectar o Elido ao HubSpot para que cada clique em um link curto apareça na timeline do contato, os valores UTM cheguem às propriedades do CRM e os limiares de volume de cliques possam impulsionar o avanço dos estágios do deal.

A estrutura se apoia em três APIs do HubSpot: a Timeline Events API para os registros por clique, a Contacts API para a gravação de propriedades e a Deals API para o avanço de estágios. A autenticação é OAuth 2.0 com os escopos documentados em HubSpot OAuth scopes. O HubSpot está ativo no Elido desde abril de 2026, e o conector lida com a rotação de tokens de atualização, novas tentativas e gravações idempotentes na timeline. O restante é configuração.

TL;DR

• Conecte via OAuth com três escopos: crm.objects.contacts.write, crm.objects.deals.read, timeline. Sem todos eles, o HubSpot rejeitará a instalação.
• O Elido publica cada clique como um Timeline Event com o eventTemplateId provisionado na instalação. Os parâmetros UTM chegam ao payload do evento e a três propriedades de contato personalizadas (elido_last_utm_source, _campaign, _medium).
• Propriedades analíticas do HubSpot como original_source_drill_down_1 são apenas de primeiro contato. Use propriedades personalizadas para atribuição contínua, não as integradas.
• Regras de limite de cliques (ex.: "50 cliques no link de proposta avança o deal para Engajado") são executadas no servidor em api-core. Configure-as nas Configurações do Workspace, não nos workflows do HubSpot.
• Erros 401 na integração quase sempre significam uma cadeia de tokens de atualização quebrada. Reinstale pelo ícone do marketplace - não cole tokens manualmente.

Como os cliques chegam à timeline do contato do HubSpot

Um clique em um link curto no Elido segue um caminho de cinco etapas antes de aparecer no HubSpot.

1. O handler de redirecionamento no edge (services/edge-redirect) lê o clique, determina o destino e grava o evento de clique no Redpanda. Este é o hot-path, com p50 de cerca de 5 ms; o HubSpot nunca está no caminho da requisição.
2. click-ingester lê o tópico do Redpanda e persiste no ClickHouse para análises.
3. O conector HubSpot dentro de api-core (anteriormente services/hubspot-connector, antes da consolidação) assina um tópico fan-out. Para cada clique em um workspace com HubSpot conectado, ele constrói um payload de Timeline Event.
4. O conector resolve o contato: se o clique carrega um contact_id do Elido (definido pelo parâmetro ?eid= ou por um dashboard compartilhado com sessão ativa), ele é mapeado diretamente para um contato do HubSpot. Se apenas fbclid ou gclid estiver presente, o Elido tenta correspondência por e-mail no último envio de formulário nos últimos 14 dias; caso contrário, o evento fica em uma fila pendente por 72 horas.
5. O conector faz POST para /crm/v3/timeline/events com o ID do template de evento provisionado na instalação. A gravação na timeline é idempotente em eventId, então novas tentativas são seguras.

O payload do evento inclui tokens para os campos estruturados que o HubSpot exibe (slug do link, URL de destino, nome da campanha, país, dispositivo) e extraData para todo o resto (conjunto UTM completo, referrer, fragmentos de user-agent, timestamp bruto). A interface da timeline do HubSpot renderiza os tokens; os extraData estão disponíveis via API, mas ocultos na visualização padrão.

O mapeamento de UTM para propriedades

Esta é a parte que prejudica as equipes que tentam fazer a conexão por conta própria. O HubSpot tem duas classes de propriedades de "fonte" e elas se comportam de forma diferente.

Propriedades analíticas (apenas primeiro contato). original_source_drill_down_1, hs_analytics_first_url, hs_analytics_first_referrer e o restante da família hs_analytics_* são definidas uma vez, quando o contato é criado pela primeira vez. Gravações subsequentes via Contacts API são silenciosamente descartadas. O HubSpot não retorna um erro - o valor simplesmente não muda. Se você já se perguntou por que seu valor de "última campanha" parece congelado em 2024, é por isso.

Propriedades personalizadas (leitura/escrita). Qualquer coisa que você defina é livremente editável. O Elido provisiona três na primeira conexão: elido_last_utm_source, elido_last_utm_campaign, elido_last_utm_medium. Cada clique aplica um PATCH a essas propriedades no contato resolvido. O rollup em nível de deal usa os valores mais recentes via um workflow do HubSpot que copia do contato principal.

A Figura 2 abaixo resume o mapeamento que o Elido aplica por padrão. Você pode substituir qualquer linha em Configurações do Workspace, Integrações, HubSpot, Mapeamento de campos. Para artigos que precisam de um mergulho mais profundo em higiene UTM, o tutorial UTM de ponta a ponta abrange as convenções de nomenclatura, e o guia de templates UTM explica como aplicá-los na criação de links.

Um exemplo real

Uma conta B2B SaaS agenda um webinar. O e-mail de acompanhamento contém um link curto do Elido para um PDF de preços com UTM utm_source=webinar&utm_campaign=q2-pricing&utm_medium=email. O destinatário clica duas vezes ao longo de dois dias. No HubSpot:

• Dois novos eventos de timeline aparecem no contato, ambos intitulados "Clique: PDF de preços Q2 (s.elido.me/abc123)".
• elido_last_utm_source = webinar, elido_last_utm_campaign = q2-pricing, elido_last_utm_medium = email.
• O original_source_drill_down_1 existente do contato (definido no setembro passado quando baixou um ebook) não muda. Este é o comportamento correto do primeiro contato, não um bug.
• A propriedade elido_recent_link_clicks do deal associado é incrementada em 2 via um workflow do HubSpot que escuta a propriedade do contato.

O AE que olha para o deal agora vê um contador de cliques crescendo antes de ligar. O marketer que conduz o webinar pode aplicar um filtro de lista do HubSpot em elido_last_utm_campaign = q2-pricing e enviá-lo para uma sequência de reengajamento. Os mesmos dados, duas perspectivas.

Conectando limiares de cliques aos estágios do deal

A visibilidade na timeline é o mínimo necessário. As regras de limite são onde a integração demonstra seu valor real, porque convertem o sinal de cliques em uma ação de CRM sem que ninguém precise monitorar um dashboard.

A estrutura de uma regra:

trigger:
  link_tag: "sales-collateral" # all links tagged this way count
  contact_window: 30d # rolling
  click_threshold: 50
action:
  type: advance_deal_stage
  pipeline: "default"
  from_stage: "appointmentscheduled"
  to_stage: "qualifiedtobuy"
  guard:
    require_associated_contact: true
    deal_amount_min: 5000 # only deals worth advancing

As regras vivem em api-core e são executadas no mesmo tópico fan-out que alimenta as gravações na timeline. Cada clique recalcula o contador acumulado por (contact_id, link_tag). Quando o contador ultrapassa o limite e o contato está associado a um deal em from_stage, o conector aplica PATCH em /crm/v3/objects/deals/{dealId} com properties.dealstage = qualifiedtobuy.

Algumas notas práticas.

Use para ativos de alta intenção. Páginas de preços, PDFs de propostas, replays de demos gravadas. O avanço baseado em limite em uma tag de link de prospecção fria vai contaminar seu pipeline em uma semana. A forma mais rápida de perder a confiança dos AEs é avançar um deal porque alguém raspou um link com curl.

O bloco guard importa. Sem require_associated_contact, cliques anônimos (alguém encaminhando o link para um amigo) podem acionar a regra. Sem deal_amount_min, você vai avançar deals de trial de R$ 2.000 para estágios reservados para oportunidades enterprise.

Regras inversas não são simétricas. O Elido não rebaixa estágios automaticamente por inatividade, porque os relatórios do HubSpot tratam reversões de estágio como suspeitas. Se você quiser lidar com deals parados, construa isso como um workflow do HubSpot em hs_lastmodifieddate, não como uma regra Elido.

Para os mecanismos de encaminhamento de conversões, o guia de encaminhamento de conversões documenta o esquema de eventos, a política de retry e a fila de dead-letter. A página de recursos de rastreamento de conversões mostra o mesmo fluxo para Meta CAPI, GA4 e Mixpanel; o HubSpot é um destino entre vários.

Escolhendo entre regras baseadas em tags e em links

Você tem duas formas de definir o escopo de uma regra de limite. As baseadas em tags cobrem um conjunto de links que compartilham uma tag (ex.: todos os 12 links da sua sequência de nurturing do Q2 contam para o mesmo limite). As baseadas em links se limitam a um único link curto.

Use as baseadas em tags quando a jornada do prospect passa por vários pontos de contato (isso é a maioria do B2B). Use as baseadas em links quando o próprio ativo é o sinal - um único link de proposta onde cliques a partir do terceiro significam que o deal é real. Ambos os tipos de regra coexistem; um engenheiro de contas configurou recentemente um workspace com 8 regras baseadas em tags e 14 baseadas em links rodando em paralelo sem conflitos.

Rotação de tokens de atualização e o erro 401 que você está prestes a ver

O OAuth do HubSpot usa tokens de atualização rotativos. Cada chamada para /oauth/v1/token com grant_type=refresh_token retorna um novo token de atualização e invalida o anterior. Isso é bom para a segurança e terrível para quem tenta gerenciar tokens manualmente.

O conector do Elido lida com a rotação corretamente. O fluxo:

1. O token de acesso expira a cada 30 minutos (padrão do HubSpot; o valor expires_in na resposta do token confirma isso).
2. Cerca de 90 segundos antes da expiração, o conector chama o endpoint de atualização com o token de atualização atual.
3. O HubSpot retorna um novo access_token + novo refresh_token + novo expires_in.
4. O Elido armazena ambos atomicamente na tabela de tokens. O token de atualização antigo está agora invalidado.

Os cenários em que isso falha:

Restaurações de banco de dados. Se você restaurar um backup mais antigo que o último refresh, o token de atualização armazenado já está invalidado no HubSpot. A primeira chamada de refresh retorna 401 com BAD_REFRESH_TOKEN. Sintoma: todas as chamadas de API do HubSpot pelo Elido falham até que você reinstale.

Cópia de tokens entre ambientes. Um desenvolvedor copia os tokens HubSpot de um workspace do staging para o local. Ambos os ambientes agora tentam atualizar contra o mesmo token. O que executar primeiro ganha; o outro morre na próxima tentativa.

Edições manuais na linha do token. Tentador ao depurar, nunca uma boa ideia. A coluna token_version é incrementada atomicamente com o refresh; edições manuais quebram a verificação de concorrência otimista e o próximo refresh falha.

Longos períodos de inatividade. O HubSpot não documenta uma expiração rígida dos tokens de atualização, mas na prática tokens não utilizados por 6 ou mais meses às vezes retornam 401. Se você tem um workspace inativo desde o verão passado, espere precisar reinstalar.

A solução em todos os quatro casos é a mesma: abra o ícone do marketplace do HubSpot nas Configurações do Workspace, clique em Reinstalar, aceite os escopos. O HubSpot emite um novo código de autorização, o Elido troca por um novo par de tokens e a integração é retomada. Nenhum dado é perdido; os eventos de timeline em fila durante a interrupção são descarregados em um minuto. A documentação OAuth do HubSpot descreve o fluxo do código de autorização com mais detalhes.

E as integrações por colagem de token?

Alguns fornecedores permitem colar um token de acesso de Private App em vez de fazer OAuth. O HubSpot suporta isso, e isso evita completamente o problema de rotação - os tokens de Private App não expiram e não rotacionam. O Elido não usa esse caminho para o HubSpot porque os Private Apps estão vinculados a uma única conta do HubSpot e não podem ser instalados em múltiplos portais a partir de um único workspace do Elido. Se você tem apenas um portal HubSpot e quer pular a instalação pelo marketplace, entre em contato via /contact; o conector suporta ambos os modos, mas não está exposto na interface padrão.

Monitorando a cadeia de atualização

Dois sinais indicam se o refresh está saudável.

O contador Prometheus hubspot_refresh_attempts_total{result="ok|error"} fica em api-core. Uma taxa de erro sustentada acima de 1% em um workspace é o alerta antecipado. A maioria dos workspaces mostra zero erros durante semanas. O guia de observabilidade explica como conectar isso a alertas.

A página de Integrações nas Configurações do Workspace mostra o timestamp do último refresh bem-sucedido por integração. Se o HubSpot diz "Última atualização: 6 dias atrás" enquanto todo o resto mostra minutos, esse é o workspace a verificar primeiro.

Colocando tudo junto

Uma sequência de implantação razoável para uma equipe que adota a integração:

1. Instale por /integrations, aceite os três escopos. Aguarde 60 segundos para que o HubSpot provisione o template de evento de timeline.
2. Confirme o primeiro clique. Envie para si mesmo um link curto do Elido com ?eid=<seu_hubspot_contact_id>, clique nele de um dispositivo diferente, atualize sua página de contato do HubSpot. O evento de timeline deve aparecer em 30 segundos.
3. Adicione as três propriedades personalizadas do Elido à sua visualização de contato. Configurações do Workspace, Contatos, Personalizar Barra Lateral. É aqui que marketing e vendas finalmente veem os mesmos valores UTM.
4. Espere duas semanas antes de configurar regras de limite. Você precisa de dados reais de cliques para saber o que "alta intenção" significa para o seu mix de ativos; os limites arbitrários definidos no dia da instalação costumam estar errados. A página de soluções para marketers e o guia introdutório de análise de links ajudam a definir o que medir.
5. Configure sua primeira regra em um único ativo de alta intenção (página de preços, link de proposta). Observe durante uma semana. Ajuste o limite e o guard do valor do deal. Repita.

O conjunto completo de recursos está documentado no catálogo de integrações e o código-fonte do conector fica no pacote hubspot em services/api-core. Se você está avaliando a plataforma de forma mais ampla, Elido pricing mostra o plano em que a integração com HubSpot está incluída (Pro e acima), e a visão geral do rastreamento de conversões no lado do servidor compara o HubSpot com os outros destinos de CRM e análise para os quais o Elido encaminha.

Uma regra prática final: trate os eventos de timeline como a fonte verdadeira de engajamento; as propriedades personalizadas como a fonte verdadeira da última campanha; nunca confie na família hs_analytics_* para nada além do primeiro contato. Esse trio cobre 95% do que marketing e vendas discutem, e o modelo de dados do HubSpot finalmente começa a parecer honesto.