HubSpot Link-Klick-Tracking: Klicks auf die Deal-Timeline schreiben

Wenn dein Vertriebsteam in HubSpot lebt, dein Kampagnen-Tracking aber in einem Short-Link-Tool, hast du zwei Timelines, die nie miteinander sprechen. Der Marketer sieht Klicks, der Account Executive sieht die Deal-Stage. Niemand sieht die Verbindung dazwischen. Diese Anleitung geht durch, wie du Elido mit HubSpot verdrahtest, damit jeder Short-Link-Klick auf der Kontakt-Timeline erscheint, UTM-Werte in CRM-Properties landen und Klickvolumen-Schwellenwerte Deal-Stages nach vorn schieben können. Für dieselbe Verdrahtung mit einem anderen CRM deckt Salesforce-Link-Tracking den Platform-Event-Weg ab.

Das Grundgerüst stützt sich auf drei HubSpot-APIs: die Timeline Events API für die Klick-für-Klick-Einträge, die Contacts API für Property-Schreibvorgänge und die Deals API für das Vorrücken der Stage. Die Authentifizierung erfolgt über OAuth 2.0 mit den unter HubSpot-OAuth-Scopes dokumentierten Scopes. Der HubSpot-Connector ist live für die OAuth-Installation, die Rotation der Refresh-Tokens und eine Shorten-Workflow-Aktion. Der Klick-für-Klick-Timeline-Feed ist im Connector bereits eingebaut, wartet aber auf Elidos Klick-Event-Stream, der auf der Roadmap steht, behandle Klick-zu-Timeline also als kommend und nicht als heute verfügbar. Der Rest ist Konfiguration.

TL;DR

• Verbinde dich über OAuth mit fünf Scopes: oauth, crm.objects.contacts.read, crm.objects.contacts.write, timeline, automation. Bei weniger lehnt HubSpot die Installation ab.
• Elido sendet jeden Klick als Timeline Event mit einer bei der Installation eingerichteten eventTemplateId. UTM-Parameter landen im Event-Payload und auf drei benutzerdefinierten Kontakt-Properties (elido_last_utm_source, _campaign, _medium).
• HubSpots Analytics-Properties wie original_source_drill_down_1 sind nur First-Touch. Nutze benutzerdefinierte Properties für laufende Attribution, nicht die eingebauten.
• Klick-Schwellenwert-Regeln (z. B. "50 Klicks auf den Angebots-Link bringt den Deal auf Engaged") laufen serverseitig in api-core. Lege sie in den Workspace-Einstellungen fest, nicht in HubSpot-Workflows.
• 401-Fehler bei der Integration bedeuten fast immer eine unterbrochene Refresh-Token-Kette. Installiere über die Marktplatz-Kachel neu, füge Tokens nicht von Hand ein.

Wie Klicks die HubSpot-Kontakt-Timeline erreichen

Ein Short-Link-Klick in Elido durchläuft fünf Schritte, bevor er in HubSpot auftaucht.

1. Der Weiterleitungs-Handler am Edge (services/edge-redirect) liest den Klick, entscheidet über das Ziel und schreibt das Klick-Event nach Redpanda. Das ist der Hot Path, p50 bei etwa 5 ms; HubSpot steht nie im Request-Pfad.
2. click-ingester liest das Redpanda-Topic und persistiert für die Analytics in ClickHouse.
3. Der HubSpot-Connector, ein eigener Service, abonniert ein Fan-out-Topic. Für jeden Klick in einem Workspace mit verbundenem HubSpot baut er ein Timeline-Event-Payload.
4. Der Connector löst den Kontakt anhand der E-Mail-Adresse auf. Er sucht nach einer Adresse in den email-Metadaten des Links, in utm_content oder in einem email=-Parameter der Ziel-URL und sucht dann in den HubSpot-Kontakten nach einer exakten Übereinstimmung. Weder E-Mail noch passender Kontakt bedeutet keinen Timeline-Eintrag für diesen Klick.
5. Der Connector sendet einen POST an /crm/v3/timeline/events mit der bei der Installation eingerichteten Event-Template-ID. Der Timeline-Schreibvorgang ist idempotent bezüglich eventId, Wiederholungen sind also unbedenklich.

Das Event-Payload trägt fünf tokens, die die HubSpot-Timeline-UI rendert: die Short-URL, die Ziel-URL, die UTM-Kampagne, die UTM-Quelle und den Klick-Zeitstempel.

Das UTM-zu-Property-Mapping

Das ist der Teil, an dem Teams scheitern, die es selbst verdrahten wollen. HubSpot hat zwei Klassen von "Quelle"-Properties, und sie verhalten sich unterschiedlich.

Analytics-Properties (nur First-Touch). original_source_drill_down_1, hs_analytics_first_url, hs_analytics_first_referrer und der Rest der hs_analytics_*-Familie werden einmal gesetzt, bei der Erstanlage des Kontakts. Spätere Schreibvorgänge über die Contacts API werden stillschweigend verworfen. HubSpot gibt keinen Fehler zurück, der Wert ändert sich einfach nicht. Falls du dich je gefragt hast, warum dein Wert für "letzte Kampagne" seit 2024 eingefroren wirkt, hier ist der Grund.

Benutzerdefinierte Properties (lesen und schreiben). Alles, was du selbst definierst, ist frei beschreibbar. Elido richtet beim ersten Connect drei ein: elido_last_utm_source, elido_last_utm_campaign, elido_last_utm_medium. Jeder Klick aktualisiert diese per PATCH auf dem aufgelösten Kontakt. Das Roll-up auf Deal-Ebene nutzt über einen HubSpot-Workflow, der vom primären Kontakt kopiert, die jeweils aktuellsten Werte.

Abbildung 2 unten fasst das Mapping zusammen, das Elido standardmäßig anwendet. Du kannst jede Zeile in den Workspace-Einstellungen unter Integrationen, HubSpot, Feld-Mapping überschreiben. Für Beiträge, die tiefer in die UTM-Hygiene einsteigen, deckt das durchgängige UTM-Tutorial Namenskonventionen ab, und die UTM-Vorlagen-Anleitung erklärt, wie du sie schon bei der Link-Erstellung erzwingst.

Ein reales Beispiel

Ein B2B-SaaS-Account bucht ein Webinar. Die Follow-up-E-Mail enthält einen Elido-Short-Link zu einem Preis-PDF mit UTM utm_source=webinar&utm_campaign=q2-pricing&utm_medium=email. Der Empfänger klickt zweimal innerhalb von zwei Tagen. In HubSpot passiert Folgendes:

• Zwei neue Timeline-Events erscheinen beim Kontakt, beide mit dem Titel "Clicked: Q2 pricing PDF (s.elido.me/abc123)".
• elido_last_utm_source = webinar, elido_last_utm_campaign = q2-pricing, elido_last_utm_medium = email.
• Das bestehende original_source_drill_down_1 des Kontakts (im letzten September gesetzt, als er ein E-Book heruntergeladen hat) ändert sich nicht. Das ist korrektes First-Touch-Verhalten, kein Bug.
• Die elido_recent_link_clicks-Property des zugehörigen Deals erhöht sich über einen HubSpot-Workflow, der auf die Kontakt-Property lauscht, um 2.

Der Account Executive, der auf den Deal schaut, sieht jetzt schon vor dem Anruf einen steigenden Klick-Zähler. Der Marketer, der das Webinar betreut, kann einen HubSpot-Listenfilter auf elido_last_utm_campaign = q2-pricing legen und ihn in eine Re-Engagement-Sequenz schicken. Dieselben Daten, zwei Sichtweisen.

Klick-Schwellenwerte mit Deal-Stages verdrahten

Timeline-Sichtbarkeit ist die Grundvoraussetzung. Schwellenwert-Regeln sind der Punkt, an dem sich die Integration wirklich lohnt, weil sie Klick-Signale ohne jemanden, der ein Dashboard beobachtet, in eine CRM-Aktion verwandeln.

Die Form einer Regel:

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

Regeln leben in api-core und laufen auf demselben Fan-out-Topic, das auch die Timeline-Schreibvorgänge versorgt. Jeder Klick berechnet den rollierenden Zähler pro (contact_id, link_tag) neu. Überschreitet der Zähler den Schwellenwert und ist der Kontakt mit einem Deal in from_stage verknüpft, aktualisiert der Connector /crm/v3/objects/deals/{dealId} per PATCH mit properties.dealstage = qualifiedtobuy.

Ein paar praktische Hinweise.

Nutze es für Assets mit hoher Kaufabsicht. Preisseiten, Angebots-PDFs, Aufzeichnungen von Demo-Wiedergaben. Schwellenwertgesteuertes Vorrücken bei einem Kaltakquise-Link-Tag verschmutzt deine Pipeline innerhalb einer Woche. Der schnellste Weg, das Vertrauen der Account Executives zu verlieren, ist ein Deal, der vorrückt, weil jemand einen Link mit curl gescraped hat.

Der guard-Block ist wichtig. Ohne require_associated_contact können anonyme Klicks (jemand leitet den Link an einen Freund weiter) die Regel auslösen. Ohne deal_amount_min rückst du 400-Dollar-Testdeals in Stages vor, die für Enterprise-Abschlüsse reserviert sind.

Rückwärtsregeln sind nicht symmetrisch. Elido stuft Stages bei Inaktivität nicht automatisch herab, weil HubSpot-Reporting Stage-Rückstufungen als verdächtig behandelt. Wenn du den Umgang mit veralteten Deals abbilden willst, baue ihn als HubSpot-Workflow auf hs_lastmodifieddate, nicht als Elido-Regel.

Für die Conversion-Forwarding-Mechanik im Hintergrund dokumentiert die Conversion-Forwarding-Anleitung das Event-Schema, die Retry-Policy und die Dead-Letter-Queue. Die Conversion-Tracking-Feature-Seite zeigt denselben Ablauf für Meta CAPI, GA4 und Mixpanel; HubSpot ist eines von mehreren Zielen.

Tag-basierte versus link-basierte Regeln wählen

Du hast zwei Möglichkeiten, eine Schwellenwert-Regel abzugrenzen. Tag-basiert deckt eine Menge Links ab, die sich ein Tag teilen (z. B. zählen alle 12 Links deiner Q2-Nurture-Sequenz auf denselben Schwellenwert). Link-basiert grenzt auf einen einzelnen Short Link ein.

Nutze tag-basiert, wenn die Reise des Interessenten mehrere Kontaktpunkte durchläuft (das ist der Großteil des B2B-Geschäfts). Nutze link-basiert, wenn das Asset selbst das Signal ist, ein einzelner Angebots-Link, bei dem ab dem dritten Klick der Deal echt wird. Beide Regeltypen können nebeneinander bestehen; ein Account Engineer hat kürzlich einen Workspace mit 8 tag-basierten und 14 link-basierten Regeln eingerichtet, die parallel und ohne Konflikte laufen.

Refresh-Token-Rotation und der 401, der dir bevorsteht

HubSpot-OAuth nutzt rotierende Refresh-Tokens. Jeder Aufruf von /oauth/v1/token mit grant_type=refresh_token liefert ein neues Refresh-Token zurück und macht das vorherige ungültig. Das ist gut für die Sicherheit und furchtbar für jeden, der versucht, Tokens von Hand zu verwalten.

Elidos Connector handhabt die Rotation korrekt. Der Ablauf:

1. Das Access-Token läuft alle 30 Minuten ab (HubSpots Standardwert; der expires_in-Wert in der Token-Antwort bestätigt das).
2. Etwa 90 Sekunden vor Ablauf ruft der Connector den Refresh-Endpunkt mit dem aktuellen Refresh-Token auf.
3. HubSpot gibt ein neues access_token, ein neues refresh_token und ein neues expires_in zurück.
4. Elido speichert beide atomar in der Token-Tabelle. Das alte Refresh-Token ist jetzt tot.

Hier bricht es typischerweise:

Datenbank-Wiederherstellungen. Wenn du ein Backup wiederherstellst, das älter ist als dein letztes Refresh, ist das gespeicherte Refresh-Token bei HubSpot bereits ungültig. Der erste Refresh-Aufruf liefert ein 401 mit BAD_REFRESH_TOKEN. Symptom: Jeder HubSpot-API-Aufruf von Elido schlägt fehl, bis du neu installierst.

Kopierte Tokens zwischen Umgebungen. Ein Entwickler kopiert die HubSpot-Tokens eines Workspace von Staging nach Lokal. Beide Umgebungen versuchen nun, gegen dasselbe Token zu refreshen. Wer zuerst läuft, gewinnt; der andere stirbt beim nächsten Versuch.

Manuelle Bearbeitung der Token-Zeile. Verlockend beim Debuggen, aber nie eine gute Idee. Die Spalte token_version wird atomar mit dem Refresh erhöht; manuelle Änderungen brechen die Optimistic-Concurrency-Prüfung, und der nächste Refresh schlägt fehl.

Lange Ausfallzeiten. HubSpot dokumentiert keine feste Ablauffrist für Refresh-Tokens, aber in der Praxis liefern Tokens, die 6 oder mehr Monate ungenutzt waren, manchmal ein 401. Wenn du einen Workspace hast, der seit letztem Sommer inaktiv war, erwarte eine Neuinstallation.

Die Lösung ist in allen vier Fällen dieselbe: Öffne die HubSpot-Marktplatz-Kachel in den Workspace-Einstellungen, klicke auf Neu installieren, akzeptiere die Scopes. HubSpot stellt einen frischen Autorisierungscode aus, Elido tauscht ihn gegen ein neues Token-Paar, und die Integration läuft wieder. Es gehen keine Daten verloren; Timeline-Events, die während des Ausfalls angesammelt wurden, werden innerhalb einer Minute nachgeliefert. Die HubSpot-OAuth-Dokumentation beschreibt den Auth-Code-Flow ausführlicher, und die Rotationsregeln sind im Abschnitt zum Refresh-Token verlinkt.

Was ist mit Token-Paste-Integrationen?

Manche Anbieter lassen dich statt OAuth einfach ein Private-App-Access-Token einfügen. HubSpot unterstützt das, und es umgeht das Rotationsproblem vollständig, Private-App-Tokens laufen nicht ab und rotieren nicht. Elido nutzt diesen Weg für HubSpot nicht, weil Private Apps an ein einzelnes HubSpot-Konto gebunden sind und sich nicht über mehrere Portale aus einem einzigen Elido-Workspace installieren lassen. Wenn du nur ein HubSpot-Portal hast und die Marktplatz-Installation überspringen willst, melde dich über /contact; der Connector unterstützt beide Modi, er ist in der Standard-UI nur nicht freigeschaltet.

Die Refresh-Kette überwachen

Zwei Signale verraten, ob der Refresh gesund läuft.

Der Prometheus-Zähler hubspot_refresh_attempts_total{result="ok|error"} liegt in api-core. Eine anhaltende Fehlerrate über 1 % für einen Workspace ist der Frühwarner. Die meisten Workspaces zeigen über Wochen hinweg null Fehler. Die Observability-Anleitung geht durch, wie du das an Alerts anschließt.

Die Integrationen-Seite in den Workspace-Einstellungen zeigt den Zeitstempel des letzten erfolgreichen Refresh pro Integration. Wenn HubSpot "Zuletzt aktualisiert: vor 6 Tagen" anzeigt, während alles andere Minuten zeigt, ist das der Workspace, den du dir zuerst ansehen solltest.

Alles zusammenfügen

Eine sinnvolle Rollout-Reihenfolge für ein Team, das die Integration einführt:

1. Installiere über /integrations, akzeptiere die fünf Scopes. Gib HubSpot 60 Sekunden, um die Timeline-Event-Vorlage bereitzustellen.
2. Bestätige den ersten Klick. Sende dir selbst einen Elido-Short-Link, dessen Ziel ?email=<deine_hubspot_kontakt_email> trägt, klicke ihn von einem anderen Gerät aus, aktualisiere deine HubSpot-Kontaktseite. Das Timeline-Event sollte innerhalb von 30 Sekunden erscheinen.
3. Füge die drei benutzerdefinierten Elido-Properties zu deiner Kontaktansicht hinzu. Workspace-Einstellungen, dann Kontakte, dann Seitenleiste anpassen. Hier sehen Marketing und Vertrieb endlich dieselben UTM-Werte.
4. Warte zwei Wochen, bevor du Schwellenwert-Regeln konfigurierst. Du brauchst echte Klickdaten, um zu wissen, wie "hohe Kaufabsicht" für deinen Asset-Mix aussieht; willkürliche Schwellenwerte am Installationstag liegen meist daneben. Die Seite zur Marketer-Lösung und der Grundlagenartikel zur Link-Analytics helfen dabei, festzulegen, was du messen solltest.
5. Richte deine erste Regel für ein einzelnes Asset mit hoher Kaufabsicht ein (Preisseite, Angebots-Link). Beobachte sie eine Woche lang. Justiere den Schwellenwert und die Deal-Betrag-Guard. Wiederhole.

Der vollständige Funktionsumfang ist im Integrationskatalog dokumentiert, und der Connector-Quellcode liegt in services/hubspot-connector. Wenn du die breitere Plattform evaluierst, deckt Elido-Preise die Stufe ab, in der die HubSpot-Integration enthalten ist (Pro und höher), und der Überblick zum serverseitigen Conversion-Tracking vergleicht HubSpot mit den anderen CRM- und Analytics-Zielen, an die Elido weiterleitet.

Eine abschließende Faustregel. Behandle die Timeline-Events als Quelle der Wahrheit für das Engagement, behandle die benutzerdefinierten Properties als Quelle der Wahrheit für die letzte Kampagne, vertraue der hs_analytics_*-Familie nie über den First-Touch hinaus. Dieses Dreiergespann deckt 95 % dessen ab, worüber Marketing und Vertrieb streiten, und HubSpots Datenmodell fühlt sich damit endlich ehrlich an.