Seguimiento de clics de enlaces de HubSpot: escribe los clics en la línea de tiempo del trato

Si tu equipo de ventas vive en HubSpot pero el seguimiento de tus campañas vive en una herramienta de enlaces cortos, tienes dos líneas de tiempo que nunca se hablan entre sí. El marketer ve los clics; el AE ve la etapa del trato. Nadie ve la línea que las conecta. Esta guía recorre cómo conectar Elido con 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 empujar las etapas del trato hacia adelante. Para la misma conexión con otro CRM, el seguimiento de enlaces de Salesforce cubre la ruta de eventos de plataforma.

La fontanería descansa en tres API de HubSpot: la API de eventos de línea de tiempo para los registros por clic, la API de contactos para las escrituras de propiedades, y la API de tratos para el avance de etapa. La autenticación es OAuth 2.0 con los permisos documentados en permisos OAuth de HubSpot. El conector de HubSpot está activo para la instalación OAuth, la rotación de tokens de actualización y una acción de flujo de trabajo Shorten. El flujo de línea de tiempo por clic está integrado en el conector, pero depende del flujo de eventos por clic de Elido, que está en la hoja de ruta, así que trata la conexión de clic a línea de tiempo como algo que llega, no como algo disponible hoy. El resto es configuración.

TL;DR

• Conéctate mediante OAuth con cinco permisos: oauth, crm.objects.contacts.read, crm.objects.contacts.write, timeline, automation. Con menos de eso, HubSpot rechazará la instalación.
• Elido publica cada clic como un evento de línea de tiempo con el eventTemplateId aprovisionado en el momento de 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 de analítica de HubSpot como original_source_drill_down_1 son solo de primer contacto. Usa propiedades personalizadas para la atribución continua, no las integradas.
• Las reglas de umbral de clics (por ejemplo, "50 clics en el enlace de la propuesta avanza el trato a Engaged") se ejecutan del lado del servidor en api-core. Configúralas en Workspace Settings, no en los flujos de trabajo de HubSpot.
• Los errores 401 en la integración casi siempre significan una cadena de tokens de actualización rota. Reinstala desde el icono del marketplace, no pegues tokens a mano.

Cómo llegan los clics a la línea de tiempo del contacto en 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, decide el destino y escribe el evento de clic en Redpanda. Este es el hot path, con un p50 de unos 5 ms; HubSpot nunca está en la ruta de la solicitud.
2. click-ingester lee el topic de Redpanda y lo persiste en ClickHouse para analítica.
3. El conector de HubSpot, un servicio aparte, se suscribe a un topic de fan-out. Por cada clic en un espacio de trabajo con HubSpot conectado, construye un payload de evento de línea de tiempo.
4. El conector resuelve el contacto por email. Busca una dirección en los metadatos email del enlace, en utm_content, o en un parámetro email= de la URL de destino, y luego busca en los contactos de HubSpot una coincidencia exacta. Sin email o sin contacto coincidente no hay escritura en la línea de tiempo para ese clic.
5. El conector envía un 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 en eventId, así que los reintentos son seguros.

El payload del evento lleva cinco tokens que la interfaz de línea de tiempo de HubSpot renderiza: la URL corta, la URL de destino, la campaña UTM, la fuente UTM y la marca de tiempo del clic.

El mapeo de UTM a propiedades

Esta es la parte que muerde a los equipos que intentan configurarlo por su cuenta. HubSpot tiene dos clases de propiedades de "origen" y se comportan de forma distinta.

Propiedades de analítica (solo primer contacto). original_source_drill_down_1, hs_analytics_first_url, hs_analytics_first_referrer y el resto de la familia hs_analytics_* se establecen una vez, cuando se crea el contacto por primera vez. Las escrituras posteriores mediante la API de contactos 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, esta es la razón.

Propiedades personalizadas (lectura/escritura). Todo lo que definas tú mismo se puede escribir libremente. Elido aprovisiona tres al conectar por primera vez: elido_last_utm_source, elido_last_utm_campaign, elido_last_utm_medium. Cada clic actualiza estas propiedades mediante PATCH en el contacto resuelto. El resumen a nivel de trato usa los valores más recientes mediante un flujo de trabajo de HubSpot que copia desde el contacto principal.

La figura 2 más abajo resume el mapeo que Elido aplica por defecto. Puedes sobrescribir cualquier fila en Workspace Settings, luego Integrations, HubSpot, Field Mapping. Para quienes necesiten profundizar en la limpieza de los UTM, el tutorial de UTM de principio a fin cubre las convenciones de nomenclatura, y la guía de plantillas UTM explica cómo aplicarlas en el momento de crear el enlace.

Un ejemplo real

Una cuenta B2B SaaS se apunta a un webinar. El email de seguimiento contiene un enlace corto de Elido a un PDF de precios con el 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 "Clicked: Q2 pricing PDF (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 septiembre pasado cuando descargó un ebook) no cambia. Este es el comportamiento correcto de primer contacto, no un error.
• La propiedad elido_recent_link_clicks del trato asociado se incrementa en 2 mediante un flujo de trabajo de HubSpot que escucha la propiedad del contacto.

El AE que mira el trato ahora ve un contador de clics subiendo antes de llamar. El marketer que organiza el webinar puede extraer un filtro de lista de HubSpot con elido_last_utm_campaign = q2-pricing y enviarlo a una secuencia de reenganche. Los mismos datos, dos vistas.

Conectar los umbrales de clics con las etapas del trato

La visibilidad en la línea de tiempo es lo mínimo indispensable. Las reglas de umbral son donde la integración se gana el sueldo, porque convierten la señal de clic en una acción del CRM sin que nadie tenga que estar mirando un panel.

La forma 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 de fan-out que alimenta las escrituras de línea de tiempo. Cada clic recalcula el recuento móvil por (contact_id, link_tag). Cuando el recuento supera el umbral y el contacto está asociado a un trato en from_stage, el conector hace PATCH a /crm/v3/objects/deals/{dealId} con properties.dealstage = qualifiedtobuy.

Unas cuantas notas prácticas.

Úsalo para activos de alta intención. Páginas de precios, PDF de propuestas, repeticiones de grabaciones de demos. El avance impulsado por umbrales 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 de un AE es avanzar un trato porque alguien rastreó un enlace con curl.

El bloque guard importa. Sin require_associated_contact, los clics anónimos (alguien que reenvía el enlace a un amigo) pueden disparar la regla. Sin deal_amount_min, avanzarás tratos de prueba de 400 dólares hacia etapas reservadas para oportunidades enterprise.

Las reglas inversas no son simétricas. Elido no retrocede etapas automáticamente por inactividad, porque los informes de HubSpot tratan los retrocesos de etapa como sospechosos. Si quieres gestionar tratos estancados, constrúyelo como un flujo de trabajo de HubSpot sobre hs_lastmodifieddate, no como una regla de Elido.

Para conocer la mecánica de reenvío de conversiones por debajo, la guía de reenvío de conversiones documenta el esquema de eventos, la política de reintentos y la cola de mensajes fallidos. La página de la función 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 o en enlaces

Tienes dos formas de delimitar el alcance de una regla de umbral. Basada en etiquetas cubre un conjunto de enlaces que comparten una etiqueta (por ejemplo, los 12 enlaces de tu secuencia de nutrición del segundo trimestre cuentan hacia el mismo umbral). Basada en enlace se limita a un único enlace corto.

Usa la opción basada en etiquetas cuando el recorrido del prospecto cruza varios puntos de contacto (esto es la mayor parte del B2B). Usa la opción basada en enlace cuando el propio activo es la señal: un único enlace de propuesta donde 3 o más clics significan que el trato es real. Ambos tipos de regla conviven; un account engineer configuró hace poco un espacio de trabajo con 8 reglas basadas en etiquetas y 14 basadas en enlace ejecutándose en paralelo sin conflicto.

Rotación de tokens de actualización y el 401 que estás a punto de ver

El OAuth de HubSpot 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 quien intente gestionar los tokens a mano.

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

1. El token de acceso expira 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 expiración, el conector llama al endpoint de actualización con el token de actualización actual.
3. HubSpot devuelve un nuevo access_token + un nuevo refresh_token + un nuevo expires_in.
4. Elido almacena ambos de forma atómica en la tabla de tokens. El antiguo token de actualización queda muerto.

Los puntos donde esto se rompe:

Restauraciones de base de datos. Si restauras una copia de seguridad más antigua que tu última actualización, el token de actualización almacenado ya está invalidado en el origen. La primera llamada de actualización devuelve un 401 con BAD_REFRESH_TOKEN. Síntomas: todas las llamadas a la API de HubSpot desde Elido fallan hasta que reinstalas.

Copias de tokens entre entornos. Un desarrollador copia los tokens de HubSpot de un espacio de trabajo desde staging a local. Ahora ambos entornos intentan renovar contra el mismo token. Gana el que se ejecute primero; el otro muere en el siguiente intento.

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

Inactividad prolongada. HubSpot no documenta una expiración estricta para los tokens de actualización, pero en la práctica los tokens sin usar durante 6 meses o más a veces devuelven 401. Si tienes un espacio de trabajo inactivo desde el verano pasado, cuenta con tener que reinstalar.

La solución en los cuatro casos es la misma: abre el icono del marketplace de HubSpot desde Workspace Settings, haz clic en Reinstall y acepta los permisos. 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 pierde ningún dato; los eventos de línea de tiempo encolados durante la interrupción se vacían en menos de un minuto. La documentación OAuth de HubSpot describe el flujo de código de autorización con más detalle, y las reglas de rotación están enlazadas desde la sección de tokens de actualización.

¿Qué pasa con las integraciones de token pegado?

Algunos proveedores te dejan pegar un token de acceso de Private App en lugar de hacer OAuth. HubSpot admite esto, y evita por completo el problema de la rotación: los tokens de Private App no expiran ni rotan. Elido no usa esta vía para HubSpot porque las Private Apps están ligadas a una única cuenta de HubSpot y no pueden instalarse en varios portales desde un único espacio de trabajo de Elido. Si solo tienes un portal de HubSpot y quieres saltarte la instalación desde el marketplace, ponte en contacto a través de /contact; el conector admite ambos modos, simplemente no está expuesto en la interfaz predeterminada.

Monitorizar la cadena de renovación

Dos señales te indican si la renovación está funcionando bien.

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

La página de Integrations en Workspace Settings muestra la marca de tiempo de la última renovación exitosa por integración. Si HubSpot dice "Last refreshed: 6 days ago" mientras todo lo demás muestra minutos, ese es el espacio de trabajo que hay que revisar primero.

Cómo encajarlo todo

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

1. Instala desde /integrations y acepta los cinco permisos. Da unos 60 segundos para que HubSpot aprovisione la plantilla de evento de línea de tiempo.
2. Confirma el primer clic. Envíate a ti mismo un enlace corto de Elido cuyo destino lleve ?email=<your_hubspot_contact_email>, haz clic en él desde otro dispositivo y actualiza tu página de contacto en HubSpot. El evento de línea de tiempo debería aparecer en menos de 30 segundos.
3. Añade las tres propiedades personalizadas de Elido a tu vista de contacto. Workspace Settings, luego Contacts, luego Customize Sidebar. 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 cómo es la "alta intención" para tu combinación de activos; los umbrales arbitrarios establecidos el día de la instalación suelen estar mal. La página de la solución para marketers y la introducción a la analítica de enlaces ayudan a definir qué medir.
5. Configura tu primera regla sobre un único activo de alta intención (página de precios, enlace de propuesta). Obsérvala durante una semana. Ajusta el umbral y el guard de importe del trato. Repite.

El conjunto completo de funciones está documentado en el catálogo de integraciones y el código fuente del conector vive en services/hubspot-connector. Si estás evaluando la plataforma en conjunto, los precios de Elido cubren el plan en el que se incluye la integración con HubSpot (Pro y superiores), y la visión general del seguimiento de conversiones del lado del servidor compara HubSpot con los demás destinos de CRM y analítica a los que Elido reenvía.

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