// stack · schnittstelle
HubSpot ist eine CRM- und Marketing-Plattform — und sie bietet zwei Wege auf eine Website: eingebettete Formulare mit Tracking-Skript oder die dokumentierte REST-API. Für siteway heißt das: Das Formular gehört zur Website, die Daten gehen serverseitig ins CRM. Diese Seite beschreibt beide Wege — und wie wir den zweiten bauen.
// definition
HubSpot ist eine cloudbasierte CRM-Plattform der HubSpot, Inc. Im Kern liegt ein gemeinsamer Datenbestand: Kontakte, Firmen, Deals und Tickets, verknüpft über Assoziationen. Darum gruppieren sich die Bereiche, die HubSpot Hubs nennt — für Marketing, Vertrieb, Service, Content und Daten. Unternehmen sammeln damit Anfragen, qualifizieren Kontakte, fahren E-Mail-Strecken und organisieren den Vertrieb entlang von Deals.
Für eine Website sind davon zwei Dinge relevant. Erstens die eingebetteten Formulare: HubSpot stellt ein Skript bereit, das ein im CRM angelegtes Formular im Browser des Besuchers aufbaut und die Absendung direkt entgegennimmt. Daneben steht das Tracking-Skript, das den Besucherverlauf erfasst und dafür einen Cookie im Browser setzt.
Zweitens die REST-API. Sie ist unter developers.hubspot.com öffentlich dokumentiert, mit Endpunkten für CRM-Objekte und für Formular-Absendungen, mit Scopes je Anwendung und mit veröffentlichten Rate Limits. Über diesen Weg liefert die Website ihr eigenes Formular aus und reicht die Daten weiter. Beide Wege enden im selben CRM — sie unterscheiden sich darin, wo der Code läuft.
// praxis
eigenes formular · serverseitig übergeben
Die erste Entscheidung fällt vor der ersten Zeile Code: eingebettet oder über die API? HubSpot bietet beides an, und beide Wege haben ihren Platz. Drei Muster helfen bei der Zuordnung.
// w-01eingebettet
Ein Skript von HubSpot baut das Formular im Browser des Besuchers auf; angegeben werden Portal-ID und Formular-ID, dazu ein Container in der Seite. Aufbau, Feldlogik und Absendung liegen beim Anbieter. Der Weg ist schnell eingerichtet — und er lädt Fremdcode, für den vorher eine Einwilligung vorliegen muss.
code: im browser
// w-02api
Die Website liefert ihr eigenes Formular aus — im Seitendesign, mit eigener Validierung, eigenen Fehlermeldungen und eigener Tastaturbedienung. Abgesendet wird an einen Endpunkt auf dem eigenen Server, der die Daten prüft und serverseitig an HubSpot weiterreicht. Das ist der Weg, den wir bauen.
code: auf dem server
// w-03kombination
Wer die Herkunft eines Leads im CRM sehen will, braucht das Tracking-Skript von HubSpot: Es setzt den Besucher-Cookie, dessen Wert das eigene Formular als hutk mitschicken kann. Dann gilt: eigenes Formular über die API, Tracking-Skript nur nach Einwilligung — und ohne Einwilligung geht die Absendung trotzdem durch.
zuordnung: nach einwilligung
Am Anfang steht das Mapping, und zwar als Dokument, bevor gebaut wird. Welches Feld im Formular geht auf welche Eigenschaft in HubSpot? Was ist Pflicht, was optional, was bleibt im Haus? Ein Formular mit vier Feldern, das vier Eigenschaften füllt, ist mehr wert als eines mit vierzehn, von denen die Hälfte niemand pflegt. Diese Zuordnung entscheidet später auch darüber, ob Auswertungen im CRM überhaupt tragen.
Dann kommt der Proxy: ein eigener Endpunkt auf dem Server der Website. Das Formular schickt seine Daten dorthin, nicht zu HubSpot. Der Endpunkt hält das Access Token — im Browser hat es nichts verloren —, prüft die Felder ein zweites Mal, verwirft, was nicht ins Mapping gehört, ergänzt Herkunftsangaben wie Seiten-URL und Seitentitel und stellt erst dann die Anfrage an HubSpot. So bestimmt der eigene Server, was das Haus verlässt.
Validierung läuft zweimal. Im Browser für die schnelle Rückmeldung — Pflichtfelder, Formate, klare Fehlertexte am Feld statt einer roten Wolke am Seitenanfang. Auf dem Server noch einmal vollständig, weil alles, was nur im Browser geprüft wird, umgangen werden kann. Wie wir Formulare aufbauen, steht in den Komponenten Formularstrecken und Lead-Magnet-Formulare.
Doppelte Absendungen fangen wir an drei Stellen ab: Der Absende-Button sperrt sich nach dem Klick, jeder Formularaufruf bekommt serverseitig ein einmaliges Kennzeichen, das nur einmal eingelöst werden kann, und im CRM dient die E-Mail-Adresse als Erkennungsmerkmal — ein vorhandener Kontakt wird aktualisiert statt neu angelegt. Aus einem hektischen Doppelklick wird so kein zweiter Datensatz.
Und schließlich das, was in Angeboten gern fehlt: der Fehlerfall. Antwortet HubSpot nicht, mit einem Fehler oder mit einer Drosselung, wird die Absendung zwischengespeichert und mit wachsendem Abstand erneut versucht. Der Absender sieht trotzdem eine Bestätigung, der Lead geht zusätzlich per E-Mail ins Haus, und der Lauf wird protokolliert. Ein Lead darf nie an einer fremden Störung verloren gehen — Details dazu in der Leistung Schnittstellenentwicklung.
// technik · 6 details
belegt aus der doku
Was hier steht, stammt aus der öffentlichen Dokumentation von HubSpot — Endpunkte, Feldnamen und Grenzwerte im Original. Was dort nicht steht, steht auch hier nicht. Zahlen zu Limits und Versionsständen ändern sich; vor dem Bauen prüfen wir sie in der Dokumentation nach.
// d-01zugang
Authentifiziert wird mit einem Access Token, das im Authorization-Header als Bearer mitgeht. Für einen einzelnen Account genügt das Token einer Private App; soll dieselbe Anbindung in mehreren HubSpot-Accounts laufen, verlangt HubSpot OAuth samt Backend für die Token-Verwaltung. Scopes legen fest, worauf eine App zugreifen darf.
zweck: authentifizierung
// d-02objekte
Die CRM-Endpunkte liegen unter Pfaden der Form /crm/objects/ und behandeln alle Objekte nach demselben Muster: Eigenschaften als Schlüssel-Wert-Paare, Assoziationen als Verknüpfung zwischen Objekten. Jeder Objekttyp hat eine feste Kennung — für Kontakte etwa 0-1. Eigene Objekttypen sind ergänzbar.
zweck: datenmodell im crm
// d-03formulare
Absendungen nimmt ein eigener Endpunkt unter api.hsforms.com entgegen, adressiert über Portal-ID und Formular-ID. Die abgesicherte Variante unter /submissions/v3/integration/secure/submit/ verlangt ein Token mit dem Scope forms — genau die, die der Server nutzt. Daneben existiert eine Variante ohne Authentifizierung.
zweck: absendung übergeben
// d-04nutzlast
Der Rumpf trägt drei Teile: fields mit Objekttyp, Name und Wert je Feld, context mit hutk, pageUri und pageName für die Herkunft, und legalConsentOptions für die Einwilligungsangaben samt gezeigtem Text. Ein mitgegebener Zeitstempel darf nicht älter als einen Monat sein.
zweck: felder & herkunft
// d-05grenzen
Privat verteilte Apps dürfen laut Dokumentation je App 100 Anfragen pro zehn Sekunden stellen (Free und Starter), 190 bei Professional und Enterprise, 250 mit gebuchter Limit-Erhöhung. Das Tageslimit gilt je Account: 250.000, 625.000 oder 1.000.000. Bei Überschreitung antwortet HubSpot mit Status 429 und nennt die gegriffene Regel.
zweck: last planen
// d-06versionen
HubSpot stellt die API von Nummern wie v3 und v4 auf datumsbasierte Versionen um. Neue Versionen erscheinen im Halbjahrestakt im März und September; jede wird 18 Monate unterstützt — sechs Monate aktiv gepflegt, danach zwölf Monate nur noch mit kritischen Korrekturen. Das macht Wartungsfenster planbar.
zweck: planbare wartung
Aus der Anbindung wird kein Schnittstellen-Diagramm, sondern eine Website. Sichtbar ist am Ende ein Formular, das zur Seite gehört — in Typografie, Farben und Abständen des Auftritts, mit Beschriftungen über den Feldern, Fehlertexten direkt am Feld und einer Bedienung, die auch ohne Maus funktioniert. Nach dem Absenden führt der Weg auf eine eigene Danke-Seite, die sich zählen und auswerten lässt.
Dahinter liegt die Übergabe. Eine Newsletter-Anmeldung wird ein Kontakt, eine Angebotsanfrage kann zusätzlich einen Deal erzeugen, der mit Kontakt und Firma verknüpft wird. Welche Felder gefüllt werden und welcher Anwendungsfall welches Objekt erzeugt, steht im Mapping — nicht im Code eines Einzelnen. Mehrere Formulare auf einer Website teilen sich dabei denselben Proxy und dieselbe Fehlerbehandlung, statt jedes für sich gebaut zu werden.
Und darunter läuft der Betrieb. Ein Token läuft irgendwann ab oder wird getauscht, ein Scope fehlt, ein Feldname ändert sich im CRM: Solche Dinge fallen nur auf, wenn jemand hinsieht. Deshalb protokollieren wir jede Übergabe mit Ergebnis, melden Häufungen von Fehlern und prüfen die Anbindung nach Änderungen am CRM gegen. Die buchbare Leistung dahinter beschreibt siteway unter Schnittstellenentwicklung.
// integration
drei systeme · ein muster
Die HubSpot-Integration bauen wir in jedem System selbst — mit den Bordmitteln, die das CMS dafür mitbringt. Die Kette ist überall dieselbe, und sie teilt sich sauber in zwei Hälften. Im CMS liegt alles, was sichtbar und pflegbar sein muss: das Formular als Inhaltselement, das die Redaktion auf einer Seite platziert, die Feldbeschriftungen, der Einwilligungstext, die Danke-Seite und die Zuordnung, welches Formular auf welches Ziel im CRM geht. Das ist Redaktionsarbeit und gehört ins Backend, nicht in eine Codezeile.
Serverseitig läuft der Rest: eine eigene Route im System nimmt die Absendung entgegen, validiert vollständig, löst das einmalige Kennzeichen gegen Doppelabsendungen ein, holt das Access Token aus der Konfiguration und stellt die Anfrage an HubSpot. Der Datenfluss setzt damit genau an einer Stelle an — zwischen dem abgeschickten Formular und dem Aufruf der API. Wo etwas regelmäßig laufen muss, etwa ein Nachlauf für zwischengespeicherte Absendungen, hängt das im Zeitplaner des jeweiligen Systems. Welches CMS darunter arbeitet, ändert an dieser Mechanik nichts — nur daran, wie die Bauteile heißen.
// cms-01typo3
TYPO3 bringt mit Extbase, TCA, dem Scheduler und Fluid alles mit, was die Anbindung braucht. Wir bauen sie als eigene Extension: Das TCA beschreibt das Datenmodell, also die Formularfelder und die Zuordnung zum Ziel im CRM. Die Absendung nimmt eine eigene Route mit passender Middleware entgegen, validiert serverseitig und ruft HubSpot auf; ein Scheduler-Task holt nach, was bei einer Störung liegen geblieben ist. Gerendert wird über Fluid-Templates, damit das Formular im Seiten-Layout sitzt statt daneben. Die Zugangsdaten stehen in der Extension-Konfiguration, nicht im Template. Die Redaktion platziert das Formular als Content-Element und pflegt Beschriftungen und Einwilligungstext im Backend.
// cms-02wordpress
In WordPress entsteht die Anbindung als eigenes Plugin und nicht als Theme-Code — so bleibt sie beim Theme-Wechsel bestehen. Eine eigene REST-Route nimmt die Absendung entgegen, prüft das Kennzeichen gegen Doppelabsendungen, validiert die Felder und ruft HubSpot serverseitig auf; der Schlüssel liegt als Konstante in der wp-config.php oder als Umgebungsvariable und nie im Frontend. Ein geplanter Lauf holt zwischengespeicherte Absendungen nach. Fürs Frontend kommen Template-Dateien und Blocks für den Editor dazu, damit die Redaktion das Formular dort platziert, wo es hingehört, und Beschriftungen sowie Danke-Seite selbst pflegt.
// cms-03statamic
Statamic läuft auf Laravel — und genau dieser Unterbau trägt die Anbindung. Ein Blueprint beschreibt das Datenmodell des Formulars, Route und Controller nehmen die Absendung entgegen, Laravels Validierung prüft die Felder, und der Aufruf an HubSpot geht über den HTTP-Client des Frameworks. Wo etwas regelmäßig laufen muss, schreiben wir einen eigenen Artisan-Command und hängen ihn in den Scheduler. Das Access Token steht in der .env, Antlers oder Blade rendern das Formular im Seiten-Layout. Im Control Panel pflegt die Redaktion Beschriftungen, Einwilligungstext und Ziel-Zuordnung.
// datenschutz
personenbezogen — also mit sorgfalt
Was durch diese Schnittstelle läuft, ist fast immer personenbezogen: Name, E-Mail-Adresse, Telefonnummer, Firma, dazu der Inhalt einer Anfrage. Damit gelten dieselben Regeln wie für jedes andere Formular auf der Website — nur mit einem zusätzlichen Empfänger. Drei Punkte klären wir vor dem Bauen.
// ds-01rechtsgrundlage
Kontaktaufnahme und Werbung sind zwei verschiedene Zwecke und brauchen zwei verschiedene Antworten. Für Newsletter und Werbestrecken ist die Einwilligung nötig — als eigene, nicht vorbelegte Angabe. Der Formular-Endpunkt sieht dafür ein Feld vor, das den gezeigten Text und die gewählten Kommunikationsarten mitschickt, sodass die Einwilligung im CRM belegt ist.
beleg: text & zeitpunkt
// ds-02datensparsamkeit
Jedes Feld im Formular braucht einen Grund. Der Proxy setzt das durch: Er kennt die Liste erlaubter Felder und schickt nichts, was nicht darauf steht — auch dann nicht, wenn jemand dem Formular unterwegs etwas hinzufügt. Dazu gehören klare Löschfristen und die Frage, welche Daten überhaupt das Haus verlassen müssen und welche im eigenen Postfach genügen.
regel: liste statt zufall
// ds-03verträge
HubSpot verarbeitet die Daten im Auftrag des Kunden und stellt dafür einen Vertrag zur Auftragsverarbeitung bereit. Der gehört abgeschlossen und ins Verzeichnis der Verarbeitungstätigkeiten, genau wie beim Hoster. In die Datenschutzerklärung gehört, welche Daten an HubSpot gehen, zu welchem Zweck und auf welcher Grundlage — in verständlichen Sätzen.
pflicht: avv & verzeichnis
Der Unterschied zwischen den beiden Wegen ist nicht nur technisch. Beim eingebetteten Formular lädt der Browser des Besuchers Code von einem fremden Server und stellt dabei selbst eine Verbindung dorthin her; Cookies können gesetzt werden. Dafür braucht es die vorherige Einwilligung — und einen Consent-Dialog, der ohne sie wirklich nichts lädt.
Beim serverseitigen Weg passiert das nicht. Der Browser spricht nur mit dem Server der Website; für die reine Übergabe der Formulardaten läuft kein Fremdcode im Browser des Besuchers. Das ersetzt keine Rechtsgrundlage für die Verarbeitung selbst — die braucht es weiterhin. Es reduziert aber die Zahl der Beteiligten, die überhaupt etwas mitbekommen, bevor jemand auf Absenden geklickt hat.
Wer zusätzlich die Herkunft eines Leads im CRM sehen will, braucht das Tracking-Skript — und damit wieder die Einwilligung. Auch das lässt sich sauber bauen: Das Formular funktioniert in jedem Fall, der Herkunftswert wird nur dann mitgeschickt, wenn er vorliegen darf. Wie wir Websites grundsätzlich ausliefern — lokale Schriften, lokale Assets, keine stillen Verbindungen nach draußen — steht im Stack unter Sicherheit & Datenschutz.
// faq
HubSpot ist eine cloudbasierte CRM-Plattform der HubSpot, Inc. Um einen gemeinsamen Datenbestand aus Kontakten, Firmen, Deals und Tickets gruppieren sich Bereiche für Marketing, Vertrieb, Service, Content und Daten — bei HubSpot Hubs genannt, etwa Marketing Hub, Sales Hub und Service Hub. Unternehmen sammeln damit Anfragen, qualifizieren Kontakte, fahren E-Mail-Strecken und organisieren den Vertrieb entlang von Deals. Für eine Website zählen davon zwei Berührungspunkte: die eingebetteten Formulare samt Tracking-Skript und die öffentlich dokumentierte REST-API.
Über zwei Wege. Der eingebettete Weg lädt ein Skript von HubSpot in die Seite, das das Formular im Browser des Besuchers aufbaut und die Absendung an HubSpot schickt; eingerichtet wird er über die Portal-ID und die Formular-ID. Der API-Weg liefert ein eigenes Formular im Design der Website aus und schickt die Eingaben an einen Endpunkt auf dem eigenen Server, der sie serverseitig an HubSpot weiterreicht. Beide Wege enden im selben CRM. Sie unterscheiden sich darin, wo der Code läuft, wer die Gestaltung bestimmt und wessen Server die Daten zuerst sieht. siteway baut den zweiten Weg.
HubSpot dokumentiert seine REST-API öffentlich unter developers.hubspot.com. Authentifiziert wird mit einem Access Token, das im Authorization-Header als Bearer mitgeht — entweder als Token einer Private App für einen einzelnen Account oder über OAuth, wenn dieselbe Anbindung in mehreren HubSpot-Accounts laufen soll. Jede App bekommt Scopes, die festlegen, worauf sie zugreifen darf. CRM-Objekte wie Kontakte, Firmen und Deals liegen unter Pfaden der Form /crm/objects/, Formular-Absendungen nimmt ein eigener Endpunkt unter api.hsforms.com entgegen. Die Versionierung stellt HubSpot dabei von v3 und v4 auf datumsbasierte Versionen um, die im Halbjahrestakt erscheinen und jeweils 18 Monate unterstützt werden.
Das eingebettete Formular ist schnell eingerichtet und braucht auf der Seite kaum mehr als einen Container: Aufbau, Feldlogik und Absendung übernimmt HubSpot. Dafür lädt Fremdcode im Browser des Besuchers, die Gestaltung folgt den Möglichkeiten des Anbieters, und für dieses Laden muss die Einwilligung vorher vorliegen. Der API-Weg passt, wenn das Formular Teil des Seitendesigns sein soll, wenn Validierung, Fehlermeldungen und Barrierefreiheit in der eigenen Hand bleiben und wenn der Server der Website entscheidet, welche Felder überhaupt hinausgehen. Kombinieren lässt sich beides: das eigene Formular über die API, das Tracking-Skript von HubSpot nur nach Einwilligung.
HubSpot dokumentiert seine Rate Limits. Für privat verteilte Apps nennt die Dokumentation je App ein Burst-Limit von 100 Anfragen pro zehn Sekunden bei Free und Starter und 190 bei Professional und Enterprise, mit gebuchter Limit-Erhöhung 250. Das Tageslimit gilt je Account und liegt bei 250.000, 625.000 beziehungsweise 1.000.000 Anfragen; es teilen sich alle Apps eines Accounts. Wird ein Limit überschritten, antwortet HubSpot mit dem Status 429 und nennt im Fehlerobjekt, welche Regel gegriffen hat. Antwort-Header wie X-HubSpot-RateLimit-Remaining zeigen den verbleibenden Rest. Für eine Website mit Formularen wird das selten eng — trotzdem behandeln wir die API als knappe Ressource: bündeln, zwischenspeichern, nur nachladen, was sich geändert hat.
Zwei Dinge sind auseinanderzuhalten. Das Laden von Fremdcode und das Setzen von Cookies im Browser des Besuchers — also eingebettetes Formular und Tracking-Skript — braucht die vorherige Einwilligung, weil dabei auf das Endgerät zugegriffen wird. Die Verarbeitung der eingegebenen Daten braucht eine eigene Rechtsgrundlage: Für die Beantwortung einer Anfrage trägt in der Regel der Kontakt selbst, für Newsletter und Werbestrecken ist es die Einwilligung. Der Formular-Endpunkt von HubSpot sieht dafür ein Feld für die Einwilligungsangaben vor, in dem der gezeigte Text und die gewählten Kommunikationsarten mitgeschickt werden. Beim serverseitigen Weg läuft für die reine Übergabe kein Fremdcode im Browser des Besuchers.
Das entscheidet der Anwendungsfall, und es wird vor dem Bauen festgelegt. Eine Newsletter-Anmeldung oder ein Whitepaper-Download wird ein Kontakt. Eine Angebotsanfrage kann zusätzlich einen Deal erzeugen, der mit diesem Kontakt und der Firma verknüpft wird — HubSpot kennt dafür eigene Objekte und Assoziationen zwischen ihnen. Damit keine Dubletten entstehen, dient die E-Mail-Adresse als Erkennungsmerkmal: Ein vorhandener Kontakt wird aktualisiert statt neu angelegt. Welche Felder dabei überhaupt gefüllt werden, steht vorher im Mapping.
Ja — und in Statamic ebenso. Die Anbindung bauen wir in jedem der drei Systeme selbst, mit dessen eigenen Bordmitteln; die dokumentierte REST-API von HubSpot macht das sauber umsetzbar. In WordPress entsteht ein eigenes Plugin statt Theme-Code: Eine eigene REST-Route nimmt die Absendung entgegen, der Aufruf an HubSpot läuft serverseitig, der Schlüssel liegt als Konstante in der wp-config.php oder als Umgebungsvariable, Template-Dateien und Blocks bringen das Formular ins Frontend. In TYPO3 bauen wir eine eigene Extension: Das TCA beschreibt das Datenmodell, eine eigene Route mit Middleware nimmt die Absendung entgegen, wiederkehrende Läufe hängen im Scheduler, gerendert wird über Fluid, die Zugangsdaten stehen in der Extension-Konfiguration. In Statamic liegt Laravel darunter: Route und Controller für die Absendung, ein Artisan-Command im Scheduler, wo etwas regelmäßig laufen muss, ein Blueprint als Datenmodell, der Schlüssel in der .env, Antlers oder Blade im Frontend. Die Integration ist damit Teil unserer Leistung — vom Formular bis zur Übergabe.
// womit das zusammenhängt
systeme, komponenten & leistung
// stack · schnittstelle
Das CRM für größere Vertriebsorganisationen — anderes Modell, dieselbe Frage: Welche Felder gehen von der Website ins System und welche nicht?
zur technik →
// stack · schnittstelle
Das schlanke Vertriebs-CRM entlang der Pipeline und wie eine Anfrage von der Website dort als Lead oder Deal ankommt.
zur technik →
// stack · schnittstelle
Wenn es nur um Newsletter geht: Anmeldung über ein eigenes Formular, Double-Opt-in und die Übergabe an die Liste.
zur technik →
// stack · grundlage
Security Header, TLS und trackingfreie Auslieferung — die Grundlage, auf der eine Formular-Anbindung überhaupt steht.
zur technik →
// komponente · buchen
Whitepaper oder Checkliste gegen E-Mail: die Formular-Komponente, die auf dieser Schnittstelle aufsetzt.
zur komponente →
// leistung · buchen
Die Technik hier, das Angebot dort: Analyse, Mapping, Umsetzung, Monitoring und Betrieb der Anbindung. Hier wird gebucht.
zur leistung →
// Leads von deiner Website direkt nach HubSpot?
Projekt anfragen