Seguimiento de clics en enlaces de HubSpot: escribir clics en la línea de tiempo del deal

Si tu equipo de ventas vive en HubSpot pero el seguimiento de campañas vive en una herramienta de enlaces cortos, tienes dos líneas de tiempo que nunca se comunican entre sí. El marketer ve clics; el AE ve etapas del deal. Nadie ve la conexión entre ellos. Esta guía explica cómo conectar Elido a HubSpot para que cada clic en un enlace corto aparezca en la línea de tiempo del contacto, los valores UTM lleguen a las propiedades del CRM y los umbrales de volumen de clics puedan impulsar el avance de las etapas del deal.

La infraestructura se apoya en tres APIs de HubSpot: la Timeline Events API para los registros de cada clic, la Contacts API para la escritura de propiedades y la Deals API para el avance de etapas. La autenticación es OAuth 2.0 con los scopes documentados en HubSpot OAuth scopes. HubSpot está activo en Elido desde abril de 2026, y el conector gestiona la rotación de tokens de actualización, los reintentos y las escrituras idempotentes en la línea de tiempo. El resto es configuración.

TL;DR

• Conéctate mediante OAuth con tres scopes: crm.objects.contacts.write, crm.objects.deals.read, timeline. Sin todos ellos, HubSpot rechazará la instalación.
• Elido publica cada clic como un Timeline Event con el eventTemplateId aprovisionado en la instalación. Los parámetros UTM llegan al payload del evento y a tres propiedades de contacto personalizadas (elido_last_utm_source, _campaign, _medium).
• Las propiedades analíticas de HubSpot como original_source_drill_down_1 son solo de primer toque. Usa propiedades personalizadas para la atribución continua, no las integradas.
• Las reglas de umbral de clics (p. ej., "50 clics en el enlace de propuesta avanza el deal a Engaged") se ejecutan en el servidor en api-core. Configúralas en la Configuración del Workspace, no en los workflows de HubSpot.
• Los errores 401 en la integración casi siempre indican una cadena de tokens de actualización rota. Reinstala desde el icono del marketplace; no pegues tokens manualmente.

Cómo los clics llegan a la línea de tiempo del contacto de HubSpot

Un clic en un enlace corto de Elido sigue un camino de cinco pasos antes de aparecer en HubSpot.

1. El manejador de redirección en el edge (services/edge-redirect) lee el clic, determina el destino y escribe el evento de clic en Redpanda. Este es el hot-path, con p50 de unos 5 ms; HubSpot nunca está en la ruta de la solicitud.
2. click-ingester lee el topic de Redpanda y persiste en ClickHouse para analytics.
3. El conector de HubSpot dentro de api-core (antes services/hubspot-connector, antes del colapso) se suscribe a un topic fan-out. Por cada clic en un workspace con HubSpot conectado, construye un payload de Timeline Event.
4. El conector resuelve el contacto: si el clic lleva un contact_id de Elido (establecido mediante el parámetro ?eid= o por un dashboard compartido con sesión iniciada), se mapea directamente a un contacto de HubSpot. Si solo hay un fbclid o gclid, Elido intenta hacer una coincidencia por correo electrónico con el último envío de formulario en los últimos 14 días; en caso contrario, el evento queda en una cola pendiente durante 72 horas.
5. El conector hace POST a /crm/v3/timeline/events con el ID de plantilla de evento aprovisionado en la instalación. La escritura en la línea de tiempo es idempotente sobre eventId, por lo que los reintentos son seguros.

El payload del evento incluye tokens para los campos estructurados que HubSpot muestra (slug del enlace, URL de destino, nombre de campaña, país, dispositivo) y extraData para todo lo demás (conjunto UTM completo, referrer, fragmentos de user-agent, timestamp en bruto). La UI de la línea de tiempo de HubSpot renderiza los tokens; el extraData está disponible mediante la API pero oculto en la vista por defecto.

El mapeo UTM a propiedades

Esta es la parte que hace tropezar a los equipos que intentan hacer la conexión por su cuenta. HubSpot tiene dos clases de propiedades de "fuente" y se comportan de forma diferente.

Propiedades analíticas (solo primer toque). original_source_drill_down_1, hs_analytics_first_url, hs_analytics_first_referrer y el resto de la familia hs_analytics_* se establecen una sola vez, cuando se crea el contacto por primera vez. Las escrituras posteriores mediante la Contacts API se descartan silenciosamente. HubSpot no devuelve ningún error, el valor simplemente no cambia. Si alguna vez te has preguntado por qué tu valor de "última campaña" parece congelado en 2024, aquí está la razón.

Propiedades personalizadas (lectura/escritura). Cualquier cosa que definas tú mismo es libremente editable. Elido aprovisiona tres al conectarse por primera vez: elido_last_utm_source, elido_last_utm_campaign, elido_last_utm_medium. Cada clic aplica un PATCH a estas en el contacto resuelto. El rollup a nivel de deal usa los valores más recientes mediante un workflow de HubSpot que copia desde el contacto principal.

La Figura 2 a continuación resume el mapeo que Elido aplica por defecto. Puedes sobrescribir cualquier fila en Configuración del Workspace, luego Integraciones, HubSpot, Mapeo de campos. Para publicaciones que necesiten profundizar en la higiene UTM, el tutorial UTM de extremo a extremo cubre las convenciones de nomenclatura, y la guía de plantillas UTM explica cómo aplicarlas al crear enlaces.

Un ejemplo real

Una cuenta B2B SaaS reserva un webinar. El correo de seguimiento contiene un enlace corto de Elido a un PDF de precios con UTM utm_source=webinar&utm_campaign=q2-pricing&utm_medium=email. El destinatario hace clic dos veces en dos días. En HubSpot:

• Aparecen dos nuevos eventos de línea de tiempo en el contacto, ambos titulados "Clic: PDF de precios Q2 (s.elido.me/abc123)".
• elido_last_utm_source = webinar, elido_last_utm_campaign = q2-pricing, elido_last_utm_medium = email.
• El original_source_drill_down_1 existente del contacto (establecido el pasado septiembre cuando descargó un ebook) no cambia. Este es el comportamiento correcto de primer toque, no un error.
• La propiedad elido_recent_link_clicks del deal asociado se incrementa en 2 mediante un workflow de HubSpot que escucha la propiedad del contacto.

El AE que mira el deal ahora ve un contador de clics en aumento antes de llamar. El marketer que gestiona el webinar puede aplicar un filtro de lista de HubSpot en elido_last_utm_campaign = q2-pricing y enviarlo a una secuencia de reactivación. Los mismos datos, dos perspectivas.

Conectar umbrales de clics con etapas del deal

La visibilidad en la línea de tiempo es el mínimo exigible. Las reglas de umbral son donde la integración demuestra su valor real, porque convierten la señal de clics en una acción de CRM sin que nadie esté vigilando un dashboard.

La estructura de una regla:

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

Las reglas viven en api-core y se ejecutan sobre el mismo topic fan-out que impulsa las escrituras en la línea de tiempo. Cada clic recalcula el conteo acumulado por (contact_id, link_tag). Cuando el conteo supera el umbral y el contacto está asociado a un deal en from_stage, el conector aplica PATCH a /crm/v3/objects/deals/{dealId} con properties.dealstage = qualifiedtobuy.

Algunas notas prácticas.

Úsalo para activos de alta intención. Páginas de precios, PDFs de propuestas, grabaciones de demos. El avance por umbral en una etiqueta de enlace de prospección en frío contaminará tu pipeline en una semana. La forma más rápida de perder la confianza del equipo de ventas es avanzar un deal porque alguien rastreó un enlace con curl.

El bloque guard es importante. Sin require_associated_contact, los clics anónimos (alguien que reenvía el enlace a un amigo) pueden activar la regla. Sin deal_amount_min, avanzarás deals de prueba de 400 € a etapas reservadas para oportunidades enterprise.

Las reglas inversas no son simétricas. Elido no degrada etapas automáticamente por inactividad, porque los informes de HubSpot tratan las inversiones de etapa como sospechosas. Si quieres gestionar deals inactivos, construye un workflow de HubSpot sobre hs_lastmodifieddate, no como una regla de Elido.

Para los detalles técnicos del reenvío de conversiones, la guía de reenvío de conversiones documenta el esquema de eventos, la política de reintentos y la cola de mensajes no entregados. La página de características de seguimiento de conversiones muestra el mismo flujo para Meta CAPI, GA4 y Mixpanel; HubSpot es un destino entre varios.

Elegir entre reglas basadas en etiquetas y en enlaces

Tienes dos formas de delimitar una regla de umbral. Las basadas en etiquetas cubren un conjunto de enlaces que comparten una etiqueta (p. ej., los 12 enlaces de tu secuencia de nurturing Q2 cuentan todos para el mismo umbral). Las basadas en enlaces se limitan a un solo enlace corto.

Usa las basadas en etiquetas cuando el recorrido del prospecto cruza múltiples puntos de contacto (esto es la mayoría del B2B). Usa las basadas en enlaces cuando el propio activo es la señal - un único enlace de propuesta donde los clics 3 o más indican que el deal es real. Ambos tipos de reglas coexisten; un ingeniero de cuentas configuró recientemente un workspace con 8 reglas basadas en etiquetas y 14 basadas en enlaces ejecutándose en paralelo sin conflictos.

La rotación de tokens de actualización y el 401 que vas a ver

HubSpot OAuth usa tokens de actualización rotativos. Cada llamada a /oauth/v1/token con grant_type=refresh_token devuelve un nuevo token de actualización e invalida el anterior. Esto es bueno para la seguridad y terrible para cualquiera que intente gestionar los tokens manualmente.

El conector de Elido gestiona la rotación correctamente. El flujo:

1. El token de acceso caduca cada 30 minutos (el valor predeterminado de HubSpot; el valor expires_in en la respuesta del token lo confirma).
2. Unos 90 segundos antes de la caducidad, el conector llama al endpoint de actualización con el token de actualización actual.
3. HubSpot devuelve un nuevo access_token + nuevo refresh_token + nuevo expires_in.
4. Elido almacena ambos de forma atómica en la tabla de tokens. El token de actualización anterior ya no es válido.

Los escenarios en los que esto falla:

Restauraciones de base de datos. Si restauras un backup anterior a tu última actualización, el token de actualización almacenado ya está invalidado en el sistema de HubSpot. La primera llamada de actualización devuelve un 401 con BAD_REFRESH_TOKEN. Síntoma: todas las llamadas a la API de HubSpot desde Elido fallan hasta que reinstales.

Copiar tokens entre entornos. Un desarrollador copia los tokens de HubSpot de un workspace de staging a local. Ambos entornos intentan actualizar contra el mismo token. El que ejecute primero gana; el otro falla en el siguiente intento.

Ediciones manuales en la fila del token. Tentador al depurar, nunca es buena idea. La columna token_version se incrementa de forma atómica con la actualización; las ediciones manuales rompen la comprobación de concurrencia optimista y la siguiente actualización falla.

Tiempos de inactividad prolongados. HubSpot no documenta una caducidad estricta de los tokens de actualización, pero en la práctica, los tokens sin uso durante 6 o más meses a veces devuelven 401. Si tienes un workspace inactivo desde el verano pasado, espera tener que reinstalar.

La solución en los cuatro casos es la misma: abre el icono del marketplace de HubSpot en la Configuración del Workspace, haz clic en Reinstalar, acepta los scopes. HubSpot emite un nuevo código de autorización, Elido lo intercambia por un nuevo par de tokens y la integración se reanuda. No se pierden datos; los eventos de línea de tiempo en cola durante la interrupción se vacían en un minuto. Los documentos OAuth de HubSpot describen el flujo del código de autorización con más detalle.

¿Qué pasa con las integraciones por pegado de tokens?

Algunos proveedores permiten pegar un token de acceso de Private App en lugar de realizar OAuth. HubSpot lo admite, y evita por completo el problema de rotación - los tokens de Private App no caducan ni rotan. Elido no usa esta vía para HubSpot porque las Private Apps están vinculadas a una sola cuenta de HubSpot y no pueden instalarse en múltiples portales desde un único workspace de Elido. Si solo tienes un portal de HubSpot y quieres saltarte la instalación del marketplace, contáctanos a través de /contact; el conector admite ambos modos, simplemente no está expuesto en la UI predeterminada.

Monitorizar la cadena de actualización

Dos señales te indican si la actualización es saludable.

El contador de Prometheus hubspot_refresh_attempts_total{result="ok|error"} vive en api-core. Una tasa de error sostenida superior al 1% en un workspace es la alerta temprana. La mayoría de los workspaces muestran cero errores durante semanas. La guía de observabilidad explica cómo conectar esto a alertas.

La página de Integraciones en la Configuración del Workspace muestra el timestamp del último refresco exitoso por integración. Si HubSpot dice "Última actualización: hace 6 días" mientras todo lo demás muestra minutos, ese es el workspace que hay que mirar primero.

Poniendo todo junto

Una secuencia de implementación razonable para un equipo que adopta la integración:

1. Instala desde /integrations, acepta los tres scopes. Espera 60 segundos para que HubSpot aprovisione la plantilla de evento de línea de tiempo.
2. Confirma el primer clic. Envíate un enlace corto de Elido con ?eid=<tu_hubspot_contact_id>, haz clic desde un dispositivo diferente, actualiza tu página de contacto de HubSpot. El evento de línea de tiempo debería aparecer en 30 segundos.
3. Agrega las tres propiedades personalizadas de Elido a tu vista de contacto. Configuración del Workspace, luego Contactos, luego Personalizar barra lateral. Aquí es donde marketing y ventas finalmente ven los mismos valores UTM.
4. Espera dos semanas antes de configurar reglas de umbral. Necesitas datos reales de clics para saber qué significa "alta intención" para tu combinación de activos; los umbrales arbitrarios establecidos el día de la instalación suelen ser incorrectos. La página de soluciones para marketers y el análisis introductorio de link analytics ayudan a enmarcar qué medir.
5. Configura tu primera regla en un único activo de alta intención (página de precios, enlace de propuesta). Observa durante una semana. Ajusta el umbral y el guard de importe del deal. Repite.

El conjunto completo de funciones está documentado en el catálogo de integraciones y el código fuente del conector vive bajo el paquete hubspot en services/api-core. Si estás evaluando la plataforma en general, Elido pricing cubre el tier donde se incluye la integración con HubSpot (Pro y superior), y la visión general del seguimiento de conversiones del lado del servidor compara HubSpot con los demás destinos de CRM y analytics a los que Elido reenvía.

Una regla final de referencia: trata los eventos de línea de tiempo como la fuente de verdad para el engagement; las propiedades personalizadas como la fuente de verdad para la última campaña; y nunca confíes en la familia hs_analytics_* para nada más allá del primer toque. Ese trío cubre el 95% de lo que discuten marketing y ventas, y el modelo de datos de HubSpot finalmente empieza a sentirse honesto.