Suivi des clics de liens HubSpot : écrire les clics dans la timeline du deal

Si votre équipe commerciale vit dans HubSpot mais que votre suivi de campagnes repose sur un outil de liens courts, vous avez deux timelines qui ne se parlent jamais. Le marketeur voit des clics ; l'AE voit des étapes de deal. Personne ne voit le lien entre les deux. Ce guide explique comment connecter Elido à HubSpot pour que chaque clic sur un lien court apparaisse dans la timeline du contact, que les valeurs UTM arrivent dans les propriétés du CRM et que des seuils de volume de clics puissent faire avancer les étapes du deal.

La plomberie repose sur trois APIs HubSpot : la Timeline Events API pour les enregistrements par clic, la Contacts API pour l'écriture des propriétés et la Deals API pour l'avancement des étapes. L'authentification se fait via OAuth 2.0 avec les scopes documentés dans HubSpot OAuth scopes. HubSpot est en production sur Elido depuis avril 2026, et le connecteur gère la rotation des tokens de rafraîchissement, les nouvelles tentatives et les écritures idempotentes dans la timeline. Le reste n'est que configuration.

TL;DR

• Connexion via OAuth avec trois scopes : crm.objects.contacts.write, crm.objects.deals.read, timeline. Sans l'un d'eux, HubSpot refusera l'installation.
• Elido publie chaque clic comme un Timeline Event avec l'eventTemplateId provisionné à l'installation. Les paramètres UTM arrivent dans le payload de l'événement et dans trois propriétés de contact personnalisées (elido_last_utm_source, _campaign, _medium).
• Les propriétés analytiques HubSpot comme original_source_drill_down_1 sont uniquement de premier contact. Utilisez des propriétés personnalisées pour l'attribution continue, pas les propriétés intégrées.
• Les règles de seuil de clics (ex. : "50 clics sur le lien de proposition font avancer le deal à Engaged") s'exécutent côté serveur dans api-core. Configurez-les dans les Paramètres du Workspace, pas dans les workflows HubSpot.
• Les erreurs 401 sur l'intégration signifient presque toujours une chaîne de tokens de rafraîchissement brisée. Réinstallez depuis la tuile du marketplace - ne collez pas de tokens manuellement.

Comment les clics arrivent dans la timeline du contact HubSpot

Un clic sur un lien court Elido suit un parcours en cinq étapes avant d'apparaître dans HubSpot.

1. Le gestionnaire de redirection au niveau de l'edge (services/edge-redirect) lit le clic, détermine la destination et écrit l'événement de clic dans Redpanda. C'est le hot-path, avec un p50 d'environ 5 ms ; HubSpot n'est jamais sur le chemin de la requête.
2. click-ingester lit le topic Redpanda et persiste dans ClickHouse pour les analytics.
3. Le connecteur HubSpot dans api-core (anciennement services/hubspot-connector avant la consolidation) s'abonne à un topic fan-out. Pour chaque clic sur un workspace avec HubSpot connecté, il construit un payload de Timeline Event.
4. Le connecteur résout le contact : si le clic porte un contact_id Elido (défini via le paramètre ?eid= ou par un partage de tableau de bord avec session active), celui-ci est mappé directement vers un contact HubSpot. Si seul un fbclid ou gclid est présent, Elido tente une correspondance par email sur le dernier envoi de formulaire dans les 14 jours ; sinon, l'événement est mis en attente dans une file pendant 72 heures.
5. Le connecteur effectue un POST vers /crm/v3/timeline/events avec l'ID du modèle d'événement provisionné à l'installation. L'écriture dans la timeline est idempotente sur eventId, les nouvelles tentatives sont donc sans risque.

Le payload de l'événement inclut des tokens pour les champs structurés qu'HubSpot affiche (slug du lien, URL de destination, nom de la campagne, pays, appareil) et extraData pour tout le reste (ensemble UTM complet, referrer, fragments de user-agent, timestamp brut). L'interface timeline de HubSpot affiche les tokens ; les extraData sont disponibles via l'API mais masqués dans la vue par défaut.

La table de correspondance UTM vers propriétés

C'est la partie qui fait trébucher les équipes qui essaient de faire le câblage elles-mêmes. HubSpot dispose de deux classes de propriétés "source" qui se comportent différemment.

Propriétés analytiques (premier contact uniquement). original_source_drill_down_1, hs_analytics_first_url, hs_analytics_first_referrer et le reste de la famille hs_analytics_* sont définis une seule fois, lors de la première création du contact. Les écritures ultérieures via la Contacts API sont silencieusement rejetées. HubSpot ne renvoie pas d'erreur, la valeur ne change simplement pas. Si vous vous êtes déjà demandé pourquoi votre valeur de "dernière campagne" semble figée en 2024, voilà pourquoi.

Propriétés personnalisées (lecture/écriture). Tout ce que vous définissez vous-même est librement modifiable. Elido en provisionne trois à la première connexion : elido_last_utm_source, elido_last_utm_campaign, elido_last_utm_medium. Chaque clic applique un PATCH sur ces propriétés du contact résolu. Le rollup au niveau du deal utilise les valeurs les plus récentes via un workflow HubSpot qui copie depuis le contact principal.

La Figure 2 ci-dessous résume le mapping qu'Elido applique par défaut. Vous pouvez remplacer n'importe quelle ligne dans Paramètres du Workspace, puis Intégrations, HubSpot, Mapping des champs. Pour des articles nécessitant une analyse approfondie de l'hygiène UTM, le tutoriel UTM de bout en bout couvre les conventions de nommage, et le guide des modèles UTM explique comment les appliquer à la création de liens.

Un exemple concret

Un compte B2B SaaS réserve un webinaire. L'e-mail de suivi contient un lien court Elido vers un PDF de tarifs avec UTM utm_source=webinar&utm_campaign=q2-pricing&utm_medium=email. Le destinataire clique deux fois sur deux jours. Dans HubSpot :

• Deux nouveaux événements de timeline apparaissent sur le contact, tous deux intitulés "Clic : PDF de tarifs Q2 (s.elido.me/abc123)".
• elido_last_utm_source = webinar, elido_last_utm_campaign = q2-pricing, elido_last_utm_medium = email.
• La propriété original_source_drill_down_1 existante du contact (définie le septembre dernier lors du téléchargement d'un ebook) ne change pas. C'est le comportement correct du premier contact, pas un bug.
• La propriété elido_recent_link_clicks du deal associé s'incrémente de 2 via un workflow HubSpot qui écoute la propriété du contact.

L'AE qui consulte le deal voit maintenant un compteur de clics augmenter avant d'appeler. Le marketeur qui gère le webinaire peut appliquer un filtre de liste HubSpot sur elido_last_utm_campaign = q2-pricing et l'envoyer vers une séquence de réengagement. Les mêmes données, deux angles de vue.

Connecter les seuils de clics aux étapes du deal

La visibilité dans la timeline est le niveau de base. Les règles de seuil sont là où l'intégration prend tout son sens, car elles convertissent le signal de clics en action CRM sans que personne surveille un tableau de bord.

La structure d'une règle :

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

Les règles vivent dans api-core et s'exécutent sur le même topic fan-out qui alimente les écritures dans la timeline. Chaque clic recalcule le compteur glissant par (contact_id, link_tag). Lorsque le compteur dépasse le seuil et que le contact est associé à un deal en from_stage, le connecteur applique un PATCH à /crm/v3/objects/deals/{dealId} avec properties.dealstage = qualifiedtobuy.

Quelques notes pratiques.

Réservez-le aux actifs à forte intention. Pages de tarifs, PDF de propositions, replays de démos enregistrées. Un avancement basé sur un seuil sur un tag de lien de prospection à froid polluera votre pipeline en une semaine. Le moyen le plus rapide de perdre la confiance des AE est de faire avancer un deal parce que quelqu'un a scrappé un lien avec curl.

Le bloc guard est essentiel. Sans require_associated_contact, des clics anonymes (quelqu'un qui transfère le lien à un ami) peuvent déclencher la règle. Sans deal_amount_min, vous ferez avancer des deals d'essai à 400 € dans des étapes réservées aux opportunités enterprise.

Les règles inverses ne sont pas symétriques. Elido ne rétrograde pas automatiquement les étapes en cas d'inactivité, car les rapports HubSpot traitent les inversions d'étape comme suspectes. Si vous souhaitez gérer les deals inactifs, construisez un workflow HubSpot sur hs_lastmodifieddate, pas comme une règle Elido.

Pour les mécanismes de transfert de conversions en coulisses, le guide de transfert de conversions documente le schéma d'événements, la politique de nouvelles tentatives et la file de lettres mortes. La page de fonctionnalités de suivi des conversions montre le même flux pour Meta CAPI, GA4 et Mixpanel ; HubSpot est l'une des nombreuses destinations.

Choisir entre règles basées sur les tags et les liens

Vous avez deux façons de définir la portée d'une règle de seuil. Les règles basées sur les tags couvrent un ensemble de liens partageant un tag (ex. : les 12 liens de votre séquence de nurturing Q2 comptent tous vers le même seuil). Les règles basées sur les liens se limitent à un seul lien court.

Utilisez les règles basées sur les tags quand le parcours du prospect traverse plusieurs points de contact (c'est la majorité du B2B). Utilisez les règles basées sur les liens quand l'actif lui-même est le signal - un lien de proposition unique où les clics 3 et plus signifient que le deal est réel. Les deux types de règles coexistent ; un ingénieur de compte a récemment configuré un workspace avec 8 règles basées sur les tags et 14 basées sur les liens fonctionnant en parallèle sans conflit.

La rotation des tokens de rafraîchissement et l'erreur 401 que vous allez rencontrer

HubSpot OAuth utilise des tokens de rafraîchissement rotatifs. Chaque appel à /oauth/v1/token avec grant_type=refresh_token renvoie un nouveau token de rafraîchissement et invalide le précédent. C'est une bonne pratique de sécurité et c'est catastrophique pour quiconque essaie de gérer les tokens manuellement.

Le connecteur d'Elido gère la rotation correctement. Le flux :

1. Le token d'accès expire toutes les 30 minutes (valeur par défaut de HubSpot ; la valeur expires_in dans la réponse du token le confirme).
2. Environ 90 secondes avant l'expiration, le connecteur appelle l'endpoint de rafraîchissement avec le token de rafraîchissement actuel.
3. HubSpot renvoie un nouvel access_token + nouveau refresh_token + nouveau expires_in.
4. Elido stocke les deux de manière atomique dans la table des tokens. L'ancien token de rafraîchissement est désormais invalide.

Les situations où cela échoue :

Restaurations de base de données. Si vous restaurez une sauvegarde antérieure à votre dernier rafraîchissement, le token de rafraîchissement stocké est déjà invalidé en amont. Le premier appel de rafraîchissement renvoie un 401 avec BAD_REFRESH_TOKEN. Symptôme : tous les appels API HubSpot depuis Elido échouent jusqu'à la réinstallation.

Copies de tokens entre environnements. Un développeur copie les tokens HubSpot d'un workspace de staging vers un environnement local. Les deux environnements tentent alors de rafraîchir avec le même token. Le premier qui s'exécute gagne ; l'autre échoue à la prochaine tentative.

Modifications manuelles de la ligne de token. Tentant lors du débogage, jamais une bonne idée. La colonne token_version est incrémentée de manière atomique lors du rafraîchissement ; les modifications manuelles brisent la vérification de concurrence optimiste et le prochain rafraîchissement échoue.

Longues périodes d'inactivité. HubSpot ne documente pas d'expiration stricte pour les tokens de rafraîchissement, mais en pratique, les tokens inutilisés pendant 6 mois ou plus renvoient parfois des 401. Si vous avez un workspace inactif depuis l'été dernier, prévoyez une réinstallation.

La solution dans les quatre cas est la même : ouvrez la tuile du marketplace HubSpot depuis les Paramètres du Workspace, cliquez sur Réinstaller, acceptez les scopes. HubSpot émet un nouveau code d'autorisation, Elido l'échange contre une nouvelle paire de tokens, et l'intégration reprend. Aucune donnée n'est perdue ; les événements de timeline mis en file pendant l'interruption se vident en une minute. La documentation OAuth de HubSpot décrit le flux du code d'autorisation plus en détail.

Qu'en est-il des intégrations par collage de token ?

Certains fournisseurs vous permettent de coller un token d'accès Private App plutôt que de faire OAuth. HubSpot le prend en charge, et cela contourne entièrement le problème de rotation - les tokens Private App n'expirent pas et ne tournent pas. Elido n'utilise pas cette voie pour HubSpot car les Private Apps sont liées à un seul compte HubSpot et ne peuvent pas être installées sur plusieurs portails depuis un unique workspace Elido. Si vous n'avez qu'un seul portail HubSpot et souhaitez passer outre l'installation depuis le marketplace, contactez-nous via /contact ; le connecteur prend en charge les deux modes, il n'est simplement pas exposé dans l'interface par défaut.

Surveiller la chaîne de rafraîchissement

Deux signaux vous indiquent si le rafraîchissement fonctionne correctement.

Le compteur Prometheus hubspot_refresh_attempts_total{result="ok|error"} vit dans api-core. Un taux d'erreur soutenu supérieur à 1% sur un workspace est l'alerte précoce. La plupart des workspaces affichent zéro erreur pendant des semaines. Le guide d'observabilité explique comment connecter cela à des alertes.

La page Intégrations dans les Paramètres du Workspace affiche le timestamp du dernier rafraîchissement réussi par intégration. Si HubSpot indique "Dernier rafraîchissement : il y a 6 jours" alors que tout le reste affiche quelques minutes, c'est le workspace à examiner en premier.

Tout mettre en place

Une séquence de déploiement raisonnable pour une équipe qui adopte l'intégration :

1. Installez depuis /integrations, acceptez les trois scopes. Attendez 60 secondes pour que HubSpot provisionne le modèle d'événement de timeline.
2. Confirmez le premier clic. Envoyez-vous un lien court Elido avec ?eid=<votre_hubspot_contact_id>, cliquez dessus depuis un autre appareil, actualisez votre page de contact HubSpot. L'événement de timeline devrait apparaître dans les 30 secondes.
3. Ajoutez les trois propriétés personnalisées Elido à votre vue de contact. Paramètres du Workspace, puis Contacts, puis Personnaliser la barre latérale. C'est là que marketing et ventes voient enfin les mêmes valeurs UTM.
4. Attendez deux semaines avant de configurer les règles de seuil. Vous avez besoin de données de clics réelles pour savoir ce que "haute intention" signifie pour votre mix d'actifs ; les seuils arbitraires définis le jour de l'installation sont généralement incorrects. La page de solutions pour marketeurs et le guide d'initiation aux analytics de liens aident à cadrer ce qu'il faut mesurer.
5. Configurez votre première règle sur un seul actif à forte intention (page de tarifs, lien de proposition). Observez pendant une semaine. Ajustez le seuil et le guard de montant de deal. Recommencez.

L'ensemble des fonctionnalités est documenté dans le catalogue des intégrations et le code source du connecteur vit sous le package hubspot dans services/api-core. Si vous évaluez la plateforme dans son ensemble, Elido pricing couvre le tier où l'intégration HubSpot est incluse (Pro et supérieur), et la présentation du suivi des conversions côté serveur compare HubSpot aux autres destinations CRM et analytics vers lesquelles Elido transfère.

Une règle empirique pour finir : considérez les événements de timeline comme la source de vérité pour l'engagement ; les propriétés personnalisées comme la source de vérité pour la dernière campagne ; ne faites jamais confiance à la famille hs_analytics_* pour autre chose que le premier contact. Ce trio couvre 95% de ce que marketing et ventes se disputent, et le modèle de données HubSpot commence enfin à paraître honnête.