HubSpot Link-Click-Tracking: Klicks in die Deal-Timeline schreiben

Wenn dein Vertriebsteam in HubSpot arbeitet, aber dein Campaign-Tracking in einem Kurzlink-Tool steckt, hast du zwei Timelines, die nie miteinander reden. Der Marketer sieht Klicks; der Account Executive sieht Deal-Stages. Niemand sieht die Verbindung dazwischen. Diese Anleitung zeigt, wie du Elido mit HubSpot verdrahtest, sodass jeder Kurzlink-Klick in der Kontakt-Timeline auftaucht, UTM-Werte in CRM-Eigenschaften landen und Klick-Volumenschwellen Deal-Stages voranbringen können.

Die Verbindung basiert auf drei HubSpot-APIs: der Timeline Events API für die einzelnen Klick-Datensätze, der Contacts API für Property-Schreibvorgänge und der Deals API für die Stage-Weiterführung. Authentifizierung läuft über OAuth 2.0 mit den unter HubSpot OAuth scopes dokumentierten Scopes. HubSpot ist seit April 2026 Live auf Elido - der Connector übernimmt Refresh-Token-Rotation, Retries und idempotente Timeline-Schreibvorgänge. Der Rest ist Konfiguration.

TL;DR

• Verbindung über OAuth mit drei Scopes: crm.objects.contacts.write, crm.objects.deals.read, timeline. Ohne alle drei lehnt HubSpot die Installation ab.
• Elido sendet jeden Klick als Timeline Event mit dem bei der Installation bereitgestellten eventTemplateId. UTM-Parameter landen im Event-Payload und in drei benutzerdefinierten Kontakteigenschaften (elido_last_utm_source, _campaign, _medium).
• HubSpot-Analyse-Eigenschaften wie original_source_drill_down_1 sind nur First-Touch. Für laufende Attribution benutzerdefinierte Eigenschaften verwenden, nicht die eingebauten.
• Click-Threshold-Regeln (z. B. "50 Klicks auf den Angebots-Link bringen den Deal auf Engaged vor") laufen serverseitig in api-core. Einstellungen erfolgen in den Workspace-Einstellungen, nicht in HubSpot-Workflows.
• 401-Fehler bei der Integration bedeuten fast immer eine unterbrochene Refresh-Token-Kette. Neuinstallation über die Marketplace-Kachel - Token nie manuell einfügen.

Wie Klicks in die HubSpot-Kontakt-Timeline gelangen

Ein Kurzlink-Klick in Elido durchläuft fünf Schritte, bevor er in HubSpot sichtbar wird.

1. Der Redirect-Handler am Edge (services/edge-redirect) liest den Klick, bestimmt das Ziel und schreibt das Klick-Event in Redpanda. Das ist der Hot-Path mit p50 von ca. 5 ms; HubSpot liegt nie auf dem Request-Pfad.
2. click-ingester liest das Redpanda-Topic und persistiert in ClickHouse für Analytics.
3. Der HubSpot-Connector innerhalb von api-core (früher services/hubspot-connector vor dem Collapse) abonniert ein Fan-Out-Topic. Für jeden Klick in einem Workspace mit verbundenem HubSpot konstruiert er einen Timeline-Event-Payload.
4. Der Connector löst den Kontakt auf: Trägt der Klick eine Elido contact_id (gesetzt über den Parameter ?eid= oder durch einen eingeloggten Dashboard-Share), wird diese direkt auf einen HubSpot-Kontakt gemappt. Ist nur eine fbclid oder gclid vorhanden, versucht Elido einen E-Mail-Abgleich mit der letzten Form-Submission innerhalb von 14 Tagen; andernfalls wird das Event 72 Stunden in einer Pending-Queue gehalten.
5. Der Connector sendet einen POST an /crm/v3/timeline/events mit der bei der Installation bereitgestellten Event-Template-ID. Der Timeline-Schreibvorgang ist idempotent auf eventId, Retries sind also sicher.

Der Event-Payload enthält tokens für die strukturierten Felder, die HubSpot anzeigt (Link-Slug, Ziel-URL, Kampagnenname, Land, Gerät) und extraData für alles andere (vollständiger UTM-Satz, Referrer, User-Agent-Fragmente, roher Zeitstempel). Die HubSpot-Timeline-UI rendert die Tokens; die extraData ist über die API verfügbar, aber in der Standardansicht ausgeblendet.

Das UTM-zu-Property-Mapping

Das ist der Teil, der Teams scheitern lässt, wenn sie die Verbindung selbst herstellen wollen. HubSpot hat zwei Klassen von "Source"-Eigenschaften mit unterschiedlichem Verhalten.

Analyse-Eigenschaften (nur First-Touch). original_source_drill_down_1, hs_analytics_first_url, hs_analytics_first_referrer und der Rest der hs_analytics_*-Familie werden einmalig gesetzt, wenn der Kontakt erstmals angelegt wird. Nachfolgende Schreibvorgänge über die Contacts API werden stillschweigend verworfen. HubSpot gibt keinen Fehler zurück - der Wert ändert sich einfach nicht. Wenn du dich je gefragt hast, warum dein "letzter Kampagnenwert" scheinbar seit 2024 eingefroren ist, liegt es genau daran.

Benutzerdefinierte Eigenschaften (lesen/schreiben). Alles selbst Definierte ist frei beschreibbar. Elido legt beim ersten Verbinden drei an: elido_last_utm_source, elido_last_utm_campaign, elido_last_utm_medium. Jeder Klick PATCHt diese auf dem aufgelösten Kontakt. Der Deal-Level-Rollup verwendet die aktuellsten Werte über einen HubSpot-Workflow, der vom primären Kontakt kopiert.

Abbildung 2 unten fasst das Mapping zusammen, das Elido standardmäßig anwendet. Jede Zeile lässt sich in den Workspace-Einstellungen unter Integrationen, HubSpot, Feld-Mapping überschreiben. Für einen tieferen Einblick in UTM-Hygiene behandelt das End-to-End-UTM-Tutorial Namenskonventionen, und der UTM-Templates-Guide erklärt, wie diese bei der Link-Erstellung durchgesetzt werden.

Ein konkretes Beispiel

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

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

Der AE, der sich den Deal ansieht, sieht nun einen steigenden Klickzähler, bevor er anruft. Der Marketer, der das Webinar betreut, kann einen HubSpot-Listen-Filter auf elido_last_utm_campaign = q2-pricing setzen und ihn an eine Re-Engagement-Sequenz schicken. Gleiche Daten, zwei Perspektiven.

Klick-Schwellen mit Deal-Stages verknüpfen

Timeline-Sichtbarkeit ist das Mindestmaß. Threshold-Regeln sind der eigentliche Mehrwert, weil sie Klick-Signale ohne manuelles Monitoring in CRM-Aktionen umwandeln.

Die Struktur 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 Timeline-Schreibvorgänge antreibt. Jeder Klick berechnet den rollierenden Zähler pro (contact_id, link_tag) neu. Wenn der Zähler den Schwellenwert überschreitet und der Kontakt mit einem Deal in from_stage verknüpft ist, PATCHt der Connector /crm/v3/objects/deals/{dealId} mit properties.dealstage = qualifiedtobuy.

Ein paar praktische Hinweise.

Nur für hochintentionale Assets verwenden. Preisseiten, Angebots-PDFs, Demo-Recordings. Schwellen-basierte Voranschiebung auf einem Kaltakquise-Link-Tag verfälscht die Pipeline innerhalb einer Woche. Der schnellste Weg, das Vertrauen der AEs zu verlieren, ist ein Deal-Advance, weil jemand einen Link mit curl abgekratzt 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 werden 400-€-Trial-Deals in Stages voranbewegt, die für Enterprise-Opportunitäten reserviert sind.

Umgekehrte Regeln sind nicht symmetrisch. Elido demotiert Stages bei Inaktivität nicht automatisch, weil HubSpot-Berichte Stage-Reversals als verdächtig behandeln. Für die Behandlung stagnierender Deals empfiehlt sich ein HubSpot-Workflow auf hs_lastmodifieddate - keine Elido-Regel.

Für die technischen Details des Conversion-Forwardings dokumentiert der Conversion-Forwarding-Guide das Event-Schema, die Retry-Richtlinie 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 vs. link-basierte Regeln wählen

Es gibt zwei Möglichkeiten, eine Threshold-Regel einzugrenzen. Tag-basiert deckt eine Gruppe von Links mit einem gemeinsamen Tag ab (z. B. zählen alle 12 Links in der Q2-Nurture-Sequenz zum selben Schwellenwert). Link-basiert begrenzt auf einen einzelnen Kurzlink.

Tag-basiert verwenden, wenn die Customer Journey mehrere Touchpoints umfasst (das ist bei B2B meistens der Fall). Link-basiert, wenn das Asset selbst das Signal ist - ein einzelner Angebots-Link, bei dem Klick 3+ bedeutet, dass der Deal real ist. Beide Regeltypen koexistieren; ein Account Engineer hat kürzlich einen Workspace mit 8 tag-basierten und 14 link-basierten Regeln eingerichtet, die parallel und konfliktfrei laufen.

Refresh-Token-Rotation und der 401, der unweigerlich kommt

HubSpot OAuth verwendet rotierende Refresh-Token. Jeder Aufruf von /oauth/v1/token mit grant_type=refresh_token gibt ein neues Refresh-Token zurück und macht das vorherige ungültig. Das ist gut für die Sicherheit und schlecht für alle, die Token manuell verwalten.

Elidos Connector behandelt die Rotation korrekt. Der Ablauf:

1. Access-Token läuft alle 30 Minuten ab (HubSpots Standard; der expires_in-Wert in der Token-Antwort bestätigt es).
2. Ca. 90 Sekunden vor Ablauf ruft der Connector den Refresh-Endpoint mit dem aktuellen Refresh-Token auf.
3. HubSpot gibt einen neuen access_token + neuen refresh_token + neues expires_in zurück.
4. Elido speichert beide atomar in der Token-Tabelle. Das alte Refresh-Token ist nun ungültig.

Die Szenarien, in denen das schiefgeht:

Datenbank-Restores. Wird ein Backup eingespielt, das älter als das letzte Refresh ist, ist das gespeicherte Refresh-Token upstream bereits ungültig. Der erste Refresh-Aufruf gibt 401 mit BAD_REFRESH_TOKEN zurück. Symptom: Alle HubSpot-API-Aufrufe von Elido schlagen fehl, bis die App neu installiert wird.

Token-Kopien zwischen Umgebungen. Ein Entwickler kopiert HubSpot-Token eines Workspaces von Staging auf Local. Beide Umgebungen versuchen nun, gegen dasselbe Token zu refreshen. Wer zuerst kommt, gewinnt; die andere Umgebung scheitert beim nächsten Versuch.

Manuelle Bearbeitungen der Token-Zeile. Verlockend beim Debuggen, nie eine gute Idee. Die Spalte token_version wird atomar mit dem Refresh inkrementiert; manuelle Bearbeitungen brechen den Optimistic-Concurrency-Check, und das nächste Refresh schlägt fehl.

Lange Ausfallzeiten. HubSpot dokumentiert keine harte Ablaufzeit für Refresh-Token, aber in der Praxis geben Token, die 6+ Monate nicht genutzt wurden, manchmal 401 zurück. Wer einen Workspace hat, der seit letztem Sommer inaktiv war, sollte mit einer Neuinstallation rechnen.

Die Lösung ist in allen vier Fällen dieselbe: HubSpot-Marketplace-Kachel in den Workspace-Einstellungen öffnen, auf Neuinstallieren klicken, Scopes akzeptieren. HubSpot stellt einen frischen Authorization-Code aus, Elido tauscht ihn gegen ein neues Token-Paar, und die Integration läuft wieder. Keine Daten gehen verloren; Timeline-Events, die während des Ausfalls eingereiht wurden, werden innerhalb einer Minute geleert. Die HubSpot-OAuth-Docs beschreiben den Auth-Code-Flow ausführlicher.

Was ist mit Token-Paste-Integrationen?

Einige Anbieter erlauben es, einen Private-App-Access-Token einzufügen statt OAuth durchzuführen. HubSpot unterstützt das, und es umgeht das Rotationsproblem vollständig - Private-App-Token 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 nicht über mehrere Portale hinweg aus einem einzigen Elido-Workspace installiert werden können. Wer nur ein HubSpot-Portal hat und die Marketplace-Installation überspringen möchte, kann sich über /contact melden; der Connector unterstützt beide Modi - er ist im Standard-UI nur nicht sichtbar.

Die Refresh-Kette überwachen

Zwei Signale zeigen, ob der Refresh gesund ist.

Der Prometheus-Counter hubspot_refresh_attempts_total{result="ok|error"} lebt in api-core. Eine anhaltende Fehlerrate über 1% in einem Workspace ist das Frühwarnsignal. Die meisten Workspaces zeigen über Wochen hinweg null Fehler. Der Observability-Guide erklärt, wie man das mit Alerts verbindet.

Die Integrationsseite in den Workspace-Einstellungen zeigt den Zeitstempel des letzten erfolgreichen Refreshs pro Integration. Wenn HubSpot "Zuletzt aktualisiert: vor 6 Tagen" anzeigt, während alle anderen wenige Minuten zeigen, ist das der Workspace, der zuerst untersucht werden sollte.

Alles zusammenbringen

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

1. Unter /integrations installieren, die drei Scopes akzeptieren. 60 Sekunden warten, damit HubSpot das Timeline-Event-Template bereitstellen kann.
2. Den ersten Klick bestätigen. Sich selbst einen Elido-Kurzlink mit ?eid=<deine_hubspot_contact_id> schicken, von einem anderen Gerät darauf klicken, die HubSpot-Kontaktseite neu laden. Das Timeline-Event sollte innerhalb von 30 Sekunden erscheinen.
3. Die drei Elido-Custom-Properties zur Kontaktansicht hinzufügen. Workspace-Einstellungen, dann Contacts, dann Sidebar anpassen. Hier sehen Marketing und Vertrieb endlich dieselben UTM-Werte.
4. Zwei Wochen warten, bevor Threshold-Regeln konfiguriert werden. Ohne echte Klickdaten lässt sich nicht wissen, was "hohe Absicht" für den eigenen Asset-Mix bedeutet; willkürliche Schwellenwerte am Installationstag sind meistens falsch. Die Marketer-Solution-Seite und der Link-Analytics-Primer helfen beim Einrahmen, was gemessen werden sollte.
5. Die erste Regel auf einem einzigen hochintentionalen Asset einrichten (Preisseite, Angebots-Link). Eine Woche beobachten. Schwellenwert und Deal-Amount-Guard anpassen. Wiederholen.

Der vollständige Feature-Umfang ist im Integrations-Katalog dokumentiert, und der Connector-Quellcode liegt unter dem hubspot-Package in services/api-core. Wer die Gesamtplattform bewertet: Elido-Pricing zeigt, in welchem Tier die HubSpot-Integration enthalten ist (Pro und höher), und der Überblick über serverseitiges Conversion-Tracking vergleicht HubSpot mit den anderen CRM- und Analytics-Zielen, an die Elido weiterleitet.

Eine abschließende Faustregel: Timeline-Events als Source of Truth für Engagement behandeln; benutzerdefinierte Eigenschaften als Source of Truth für die aktuelle Kampagne; der hs_analytics_*-Familie niemals für mehr als First-Touch vertrauen. Dieses Triplett deckt 95% der Streitpunkte zwischen Marketing und Vertrieb ab, und HubSpots Datenmodell fühlt sich endlich ehrlich an.