Rastreamento de cliques de link no HubSpot: gravando cliques na linha do tempo do negócio

Se sua equipe de vendas vive no HubSpot, mas o rastreamento de campanhas vive em uma ferramenta de link curto, você tem duas linhas do tempo que nunca conversam entre si. O profissional de marketing vê cliques; o AE vê o estágio do negócio. Ninguém vê a ligação entre os dois. Este guia percorre como conectar o Elido ao HubSpot para que todo clique em link curto apareça na linha do tempo do contato, os valores de UTM caiam em propriedades do CRM, e limites de volume de clique possam empurrar estágios de negócio para frente. Para a mesma conexão com um CRM diferente, rastreamento de link do Salesforce cobre o caminho de eventos de plataforma.

O encanamento se apoia em três APIs do HubSpot: a Timeline Events API para os registros por clique, a Contacts API para escritas de propriedade e a Deals API para avanço de estágio. A autenticação é OAuth 2.0 com os escopos documentados em Escopos OAuth do HubSpot. O conector do HubSpot está ativo para a instalação OAuth, a rotação de refresh token e uma ação de workflow Shorten. O feed de timeline por clique está embutido no conector, mas depende do fluxo de eventos por clique do Elido, que está no roadmap, então trate o clique-para-timeline como algo a caminho em vez de disponível hoje. O resto é configuração.

Resumo rápido

• Conecte via OAuth com cinco escopos: oauth, crm.objects.contacts.read, crm.objects.contacts.write, timeline, automation. Qualquer coisa a menos e o HubSpot vai rejeitar a instalação.
• O Elido posta cada clique como um Timeline Event com eventTemplateId provisionado na instalação. Os parâmetros de UTM caem no payload do evento e em três propriedades de contato personalizadas (elido_last_utm_source, _campaign, _medium).
• Propriedades de analytics do HubSpot como original_source_drill_down_1 são apenas de primeiro toque. Use propriedades personalizadas para atribuição contínua, não as embutidas.
• Regras de limite de clique (por exemplo, "50 cliques no link da proposta avança o negócio para Engajado") rodam no lado do servidor em api-core. Defina-as em Configurações do Workspace, não em workflows do HubSpot.
• Erros 401 na integração quase sempre significam uma cadeia de refresh token quebrada. Reinstale pelo card do marketplace, não cole tokens manualmente.

Como os cliques chegam à linha do tempo de contato do HubSpot

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

1. O manipulador de redirecionamento na borda (services/edge-redirect) lê o clique, decide o destino e grava o evento de clique no Redpanda. Este é o caminho quente, p50 em torno de 5ms; o HubSpot nunca está no caminho da requisição.
2. O click-ingester lê o tópico do Redpanda e persiste no ClickHouse para analytics.
3. O conector do HubSpot, um serviço separado, assina um tópico de fan-out. Para cada clique em um workspace com o HubSpot conectado, ele constrói um payload de Timeline Event.
4. O conector resolve o contato pelo e-mail. Ele procura um endereço nos metadados email do link, no utm_content, ou em um parâmetro email= na URL de destino, e então busca nos contatos do HubSpot uma correspondência exata. Sem e-mail ou sem contato correspondente significa nenhuma escrita de timeline para aquele clique.
5. O conector faz um POST para /crm/v3/timeline/events com o ID do template de evento provisionado na instalação. A escrita de timeline é idempotente em eventId, então as repetições são seguras.

O payload do evento carrega cinco tokens que a interface de timeline do HubSpot renderiza: a URL curta, a URL de destino, a campanha de UTM, a origem de UTM e o timestamp do clique.

O mapa de UTM para propriedade

Esta é a parte que pega as equipes que tentam configurar isso sozinhas. O HubSpot tem duas classes de propriedades de "origem" e elas se comportam de forma diferente.

Propriedades de analytics (apenas primeiro toque). original_source_drill_down_1, hs_analytics_first_url, hs_analytics_first_referrer, e o resto da família hs_analytics_* são definidas uma vez, quando o contato é criado pela primeira vez. Escritas posteriores 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 o valor da sua "última campanha" parece congelado em 2024, é por isso.

Propriedades personalizadas (leitura/escrita). Qualquer coisa que você defina sozinho é livremente gravável. O Elido provisiona três na primeira conexão: elido_last_utm_source, elido_last_utm_campaign, elido_last_utm_medium. Cada clique faz um PATCH nessas propriedades do contato resolvido. O rollup em nível de negócio 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 sobrescrever qualquer linha em Configurações do Workspace, depois Integrações, HubSpot, Mapeamento de Campos. Para posts que precisam de um mergulho mais profundo em higiene de UTM, o tutorial de UTM de ponta a ponta cobre convenções de nomenclatura, e o guia de templates de UTM explica como aplicá-las no momento da criação do link.

Um exemplo real

Uma conta B2B SaaS reserva um webinar. O e-mail de follow-up 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 "Clicou: PDF de preços do 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 em setembro passado quando ele baixou um ebook) não muda. Esse é o comportamento correto de primeiro toque, não um bug.
• A propriedade elido_recent_link_clicks do negócio associado incrementa em 2 via um workflow do HubSpot que escuta a propriedade do contato.

O AE que olha o negócio agora vê um contador de cliques subindo antes de ligar. O profissional de marketing que roda o webinar pode puxar 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 visões.

Conectando limites de clique a estágios de negócio

A visibilidade na timeline é o mínimo esperado. As regras de limite são onde a integração realmente se paga, porque convertem sinal de clique em uma ação no CRM sem ninguém olhando um painel.

A forma 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 rodam no mesmo tópico de fan-out que alimenta as escritas de timeline. Cada clique recalcula a contagem móvel por (contact_id, link_tag). Quando a contagem ultrapassa o limite e o contato está associado a um negócio em from_stage, o conector faz um PATCH em /crm/v3/objects/deals/{dealId} com properties.dealstage = qualifiedtobuy.

Algumas notas práticas.

Use isso para ativos de alta intenção. Páginas de preços, PDFs de proposta, replays de gravação de demo. O avanço guiado por limite em uma tag de link de prospecção fria vai poluir seu pipeline em uma semana. A forma mais rápida de perder a confiança dos AEs é avançar um negócio 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 disparar a regra. Sem deal_amount_min, você vai avançar negócios de teste de 400 dólares para estágios reservados a contas enterprise.

Regras reversas 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 negócios parados, construa isso como um workflow do HubSpot em hs_lastmodifieddate, não como uma regra do Elido.

Para a mecânica de encaminhamento de conversão por trás disso, o guia de encaminhamento de conversão documenta o esquema de evento, a política de retry e a fila de dead-letter. A página do recurso de rastreamento de conversão mostra o mesmo fluxo para Meta CAPI, GA4 e Mixpanel; o HubSpot é um destino entre vários.

Escolhendo entre regras baseadas em tag ou em link

Você tem duas formas de delimitar uma regra de limite. Baseada em tag cobre um conjunto de links que compartilham uma tag (por exemplo, todos os 12 links da sua sequência de nutrição do Q2 contam para o mesmo limite). Baseada em link delimita para um único link curto.

Use baseada em tag quando a jornada do prospect cruza vários pontos de contato (é a maioria do B2B). Use baseada em link quando o próprio ativo é o sinal - um único link de proposta onde 3 ou mais cliques significam que o negócio é real. Os dois tipos de regra coexistem; um account engineer recentemente configurou um workspace com 8 regras baseadas em tag e 14 baseadas em link rodando em paralelo sem conflito.

Rotação de refresh token e o 401 que você está prestes a ver

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

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

1. O access token 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 de expirar, o conector chama o endpoint de refresh com o refresh token atual.
3. O HubSpot retorna um novo access_token + novo refresh_token + novo expires_in.
4. O Elido armazena os dois atomicamente na tabela de tokens. O refresh token antigo agora está morto.

Os lugares onde isso quebra:

Restaurações de banco de dados. Se você restaurar um backup mais antigo que seu último refresh, o refresh token armazenado já foi invalidado no lado do HubSpot. A primeira chamada de refresh retorna um 401 com BAD_REFRESH_TOKEN. Sintomas: toda chamada de API do HubSpot pelo Elido falha até você reinstalar.

Cópias de token entre ambientes. Um desenvolvedor copia os tokens do HubSpot de um workspace do staging para o local. Os dois ambientes agora tentam fazer refresh contra o mesmo token. O que rodar primeiro ganha; o outro morre na próxima tentativa.

Edições manuais na linha do token. Tentador ao debugar, nunca uma boa ideia. A coluna token_version é incrementada atomicamente junto 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 para refresh tokens, mas na prática tokens não usados por 6 meses ou mais às vezes retornam 401. Se você tem um workspace inativo desde o verão passado, espere ter que reinstalar.

A correção nos quatro casos é a mesma: abra o card do marketplace do HubSpot em Configurações do Workspace, clique em Reinstalar, aceite os escopos. O HubSpot emite um novo código de autorização, o Elido o troca por um novo par de tokens, e a integração retoma. Nenhum dado é perdido; eventos de timeline enfileirados durante a indisponibilidade são liberados em um minuto. A documentação de OAuth do HubSpot descreve o fluxo de código de autorização com mais detalhes, e as regras de rotação estão linkadas na seção de refresh token.

E as integrações por colagem de token?

Alguns fornecedores deixam você colar um access token de Private App em vez de fazer OAuth. O HubSpot aceita isso, e isso contorna completamente o problema de rotação - tokens de Private App não expiram e não giram. O Elido não usa esse caminho para o HubSpot porque Private Apps estão vinculados a uma única conta do HubSpot e não conseguem instalar em vários portais a partir de um único workspace do Elido. Se você tem apenas um portal do HubSpot e quer pular a instalação pelo marketplace, entre em contato pelo /contact; o conector aceita os dois modos, só não está exposto na interface padrão.

Monitorando a cadeia de refresh

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

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

A página de Integrações em Configurações do Workspace mostra o timestamp do último refresh bem-sucedido por integração. Se o HubSpot mostra "Último refresh: 6 dias atrás" enquanto tudo o mais mostra minutos, esse é o workspace a olhar primeiro.

Juntando tudo

Uma sequência de lançamento razoável para uma equipe adotando a integração:

1. Instale a partir de /integrations, aceite os cinco escopos. Reserve 60 segundos para o HubSpot provisionar o template de evento de timeline.
2. Confirme o primeiro clique. Envie para você mesmo um link curto do Elido cujo destino carregue ?email=<seu_email_de_contato_hubspot>, clique nele de um dispositivo diferente, atualize sua página de contato no HubSpot. O evento de timeline deve aparecer em até 30 segundos.
3. Adicione as três propriedades personalizadas do Elido à sua visualização de contato. Configurações do Workspace, depois Contatos, depois Personalizar Barra Lateral. É aí que marketing e vendas finalmente enxergam os mesmos valores de UTM.
4. Espere duas semanas antes de configurar regras de limite. Você precisa de dados reais de clique para saber como é a "alta intenção" para o seu mix de ativos; limites arbitrários definidos no dia da instalação geralmente estão errados. A página da solução para profissionais de marketing e o manual de analytics de link 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 por uma semana. Ajuste o limite e a proteção de valor do negócio. Repita.

O conjunto completo de recursos está documentado no catálogo de integrações e o código do conector vive em services/hubspot-connector. Se você está avaliando a plataforma mais ampla, os preços do Elido cobrem o nível em que a integração com HubSpot está incluída (Pro e acima), e a visão geral de rastreamento de conversão server-side compara o HubSpot com os outros destinos de CRM e analytics para os quais o Elido encaminha.

Uma regra de ouro final. Trate os eventos de timeline como a fonte da verdade para engajamento; trate as propriedades personalizadas como a fonte da verdade para a campanha mais recente; nunca confie na família hs_analytics_* para nada além do primeiro toque. Esse trio cobre 95% do que marketing e vendas discutem, e o modelo de dados do HubSpot finalmente começa a parecer honesto.