HubSpot API

HubSpot-Integration einrichten und nutzen

Die HubSpot-Integration verbindet dein HubSpot-Konto bidirektional mit Oniva:

• Import: Du übernimmst Kontakte aus einer HubSpot-Liste direkt in dein Event.
• Export via Marketing-Events: Oniva legt deine Events samt Kontaktstatus automatisch in HubSpot an und überträgt neue Kontakte.
• Export via Custom Object: Oniva überträgt persönliche Event-Links als eigene Objekt-Datensätze nach HubSpot, z. B. zur Verwendung in HubSpot-E-Mails oder Workflows

Voraussetzungen

• Das kostenpflichtige Add-on "HubSpot API" von Oniva muss für deinen Mandanten aktiviert sein. Kontaktiere den Oniva-Support oder deine:n Kundenbetreuer:in für die Aktivierung.
• Für das Erstellen einer Private App in HubSpot benötigst du Mandanten-Admin-Rechte.
• Der Export persönlicher Event-Links über Custom Objects setzt einen HubSpot-Enterprise-Tarif voraus, da Custom Objects nur in Enterprise-Konten verfügbar sind. Import und Marketing-Events-Export funktionieren auch in tieferen Tarifen, sofern dort Private Apps unterstützt werden.

‍

Schritt 1: Access Token in HubSpot erstellen

In HubSpot:

1. Klicke auf das Zahnrad-Symbol (Settings) oben in der Navigationsleiste.
2. Navigiere in der linken Sidebar zu Integrations → Private Apps.
3. Klicke auf eine bestehende App oder erstelle eine neue App. Vergib der App einen aussagekräftigen Namen (z. B. „Oniva Integration").
   ⚠️ Hinweis: Private Apps werden in HubSpot teilweise als „Alte App“ oder „Legacy App“ angezeigt. Sie können dennoch für die Integration mit Oniva verwendet werden.
4. Wechsle zum Tab „Scopes" und aktiviere die Berechtigungen entsprechend deinem Anwendungsfall (siehe Liste unten).
5. Speichere die App und wechsle zum Tab „Authentifizierung".
6. Klicke auf „Show token" und anschliessend auf „Copy".
7. Füge den Access Token in Oniva unter App-Verbindungen ein (siehe Schritt 2).

Erforderliche Scopes

Aktiviere mindestens die Scopes, die zu den von dir genutzten Funktionen passen. Aktiviere bewusst nur die tatsächlich benötigten Berechtigungen.

Für den Import von Kontakten aus HubSpot in Oniva:

• crm.lists.read
• crm.schemas.contacts.read
• crm.objects.contacts.read

Zusätzlich für den Export von Eventdaten aus Oniva (Marketing-Events):

• crm.objects.contacts.write
• crm.objects.marketing_events.read
• crm.objects.marketing_events.write

Zusätzlich für den Export persönlicher Event-Links (Custom Object, nur HubSpot Enterprise):

• crm.schemas.custom.read
• crm.objects.custom.read
• crm.objects.custom.write

👉 Hinweis: Fehlende Scopes lassen sich jederzeit nachträglich in der bestehenden App ergänzen, ohne eine neue App anlegen zu müssen.

Statischer vs. rotierender Token

HubSpot bietet beide Optionen an. Für eine stabile, unterbrechungsfreie Verbindung empfehlen wir einen statischen (fixen) Token. Dieser läuft nicht ab und muss nicht erneuert werden. Wenn du aus Sicherheitsgründen einen rotierenden Token verwendest, denke daran, den Token in Oniva nach jeder Rotation sofort zu aktualisieren, andernfalls wird die Verbindung unterbrochen.

‍

Schritt 2: HubSpot in Oniva verbinden

1. Navigiere in Oniva zur Mandanten-Übersicht und wähle "App-Verbindungen" aus.
2. Wähle HubSpot aus der Liste und füge den kopierten Access Token ein.
3. Lege fest, ob HubSpot nur für den Import von Kontakten oder zusätzlich für den Export von Eventdaten aktiviert werden soll. Beim Export stehen zwei Funktionen zur Verfügung, die du einzeln aktivieren kannst:
   
   1. Marketing-Events-Synchronisation: Legt neue Events inklusive Kontaktstatus in HubSpot an und überträgt neue Kontakte nach HubSpot.
   2. Custom Objects: Ermöglicht die Übertragung persönlicher Event-Links an HubSpot.
4. Bestätige die Verbindung.

⚠️ Wichtig: Die hier gewählten Funktionen müssen durch die entsprechenden Scopes deines Access Tokens abgedeckt sein (siehe Schritt 1). Aktivierst du z. B. Custom Objects, ohne die Custom-Object-Scopes vergeben zu haben, schlägt die Übertragung fehl.

‍

Schritt 3: App-Verbindung auf Workspace und Event aktivieren

Die Verbindung muss zusätzlich auf Workspace- und Event-Ebene freigeschaltet werden.

1. Öffne die Einstellungen des gewünschten Workspace und gehe zu "App-Verbindung" → "aktivieren".
2. Öffne das gewünschte Event und gehe ebenfalls zu "App-Verbindung" → "aktivieren".

Nach der Aktivierung stehen die HubSpot-Kontakte im Event beim Kontakt-Import zur Verfügung. Wurde zusätzlich die Marketing-Events-Synchronisation aktiviert, werden Eventdaten ab diesem Zeitpunkt automatisch an HubSpot übertragen (siehe Abschnitt "Export").

‍

Import: Kontakte aus HubSpot in ein Event übernehmen

Sobald die App-Verbindung auf Event-Ebene aktiviert ist, kannst du Kontakte aus einer HubSpot-Liste direkt importieren.

1. Navigiere im Event-Dashboard zu "Kontakte".
2. Wähle "Kontakte importieren".
3. Wähle die gewünschte HubSpot-Liste aus.
4. Wähle als Import-Modus "Neue Kontakte anlegen".
5. Weise die Felder aus HubSpot den entsprechenden Feldern in Oniva zu.
6. Klicke auf "Kontakte importieren", um den Import abzuschliessen.

Nachträglich hinzugefügte Kontakte synchronisieren

HubSpot-Kontakte werden nicht automatisch in Oniva nachgeführt. Wenn im Verlauf des Events weitere Kontakte zur HubSpot-Liste hinzugekommen sind oder bestehende Kontakte aktualisiert wurden, muss der Import manuell wiederholt werden.

1. Navigiere im Event-Dashboard zu „Kontakte".
2. Wähle „Kontakte importieren".
3. Wähle die gewünschte HubSpot-Liste aus (siehe Segmente in HubSpot).
4. Wähle als Import-Modus „Neue Kontakte hinzufügen oder existierende Kontakte aktualisieren".
5. Weise die Felder aus HubSpot den entsprechenden Feldern in Oniva zu.
6. Klicke auf „Kontakte importieren", um die Synchronisation abzuschliessen.

👉 Hinweis: Dieser Vorgang kann jederzeit wiederholt werden, ohne bestehende Kontakte zu duplizieren. Bereits vorhandene Kontakte werden aktualisiert, neue Kontakte werden ergänzt.

‍

Import: Kontakte aus HubSpot als Konten in Oniva anlegen

Neben dem Kontakt-Import auf Event-Ebene kannst du HubSpot-Kontakte auch als Konten (User-Accounts) in Oniva anlegen. Dies eignet sich, um Personen Zugang zu Oniva zu geben. Für das Importieren von Konten werden Mandanten-Admin-Rechte benötigt.

1. Wähle über das Zahnrad die Einstellung „Konten".
2. Wähle „Konten importieren".
3. Wähle HubSpot als Quelle.
4. Wähle die gewünschte HubSpot-Liste aus (siehe Segmente in HubSpot).
5. Wähle den Kontotyp, falls mehrere vorhanden sind (z. B. SSO).
6. Wähle „Neue Konten hinzufügen oder bestehende aktualisieren".
7. Weise die Felder aus HubSpot den entsprechenden Feldern in Oniva zu.
8. Wähle „Import starten".

Nach erfolgtem Import stehen die Konten in Oniva zur Verfügung. Mit "alle auswählen" und der Aktion "Konten aktivieren" erhalten alle User ein Aktivierungs-E-Mail, um ihr Konto anzulegen.

‍

Export: Eventdaten via Marketing Events nach HubSpot übertragen

Ist die Marketing-Events-Synchronisation aktiviert (Schritt 2) und die App-Verbindung auf Workspace- und Event-Ebene freigeschaltet (Schritt 3), überträgt Oniva Eventdaten automatisch an HubSpot. Ein manueller Export ist nicht erforderlich.

Was wird übertragen?

• Pro Oniva-Event wird in HubSpot genau ein Marketing Event angelegt. Ein Oniva-Event kann nicht auf mehrere HubSpot Marketing Events abgebildet werden (1:1-Zuordnung).
• Pro Teilnehmer:in wird der Kontaktstatus (z. B. registriert, zu-/abgesagt, teilgenommen) auf das Marketing Event gebucht.
• Kontakte, die in HubSpot noch nicht existieren, werden als neue Kontakte angelegt.

Wann wird übertragen?

Die Übertragung erfolgt automatisch, sobald in Oniva eine Buchung erstellt wird oder sich der Status eines Teilnehmers ändert. Im Gegensatz zum Import (manuell) ist die Marketing-Events-Synchronisation also ein laufender, ereignisgesteuerter Vorgang.

So prüfst du das Ergebnis in HubSpot:

1. Öffne in HubSpot das Menü "Marketing" → "Marketing Events" (bzw. die entsprechende Objektübersicht).
2. Suche das Event nach Namen und öffne den Datensatz.
3. Unter den zugeordneten Kontakten siehst du die übertragenen Teilnehmer:innen samt Status.

💡 Tipp: HubSpot-Ansicht anpassen
Für eine übersichtliche Darstellung der Eventteilnahmen empfiehlt es sich, Marketing-Events in HubSpot als Kartenelement auf der rechten Seite des Kontaktdatensatzes anzuzeigen.
Die Standardansicht lässt sich in HubSpot unter Einstellungen (Zahnrad oben rechts) → Datenmanagement → Anpassung von Datensätzen anpassen. Dort kann die Ansicht des Kontaktdatensatzes so konfiguriert werden, dass Marketing-Events als Karte eingeblendet werden.

‍

Export: Persönliche Event-Links via Custom Object übertragen

Persönliche Event-Links (individuelle Teilnahme-Links pro Kontakt) werden über ein HubSpot Custom Object übertragen. So lassen sie sich in HubSpot weiterverwenden, etwa als personalisierter Link in Marketing-E-Mails oder als Auslöser in Workflows.

Voraussetzungen

• HubSpot-Enterprise-Tarif (Custom Objects sind nur in Enterprise-Konten verfügbar).
• Die Custom-Object-Scopes im Access Token (siehe Schritt 1).
• Die Funktion Custom Objects in der Oniva-App-Verbindung aktiviert (Schritt 2).

Ablauf

1. Stelle sicher, dass die oben genannten Voraussetzungen erfüllt sind.
2. Sobald in einem Event persönliche Links erzeugt werden, überträgt Oniva diese als Datensätze des Custom Objects an HubSpot und verknüpft sie mit dem jeweiligen Kontakt. Übertragen wird ausschliesslich der persönliche Link – keine weiteren Felder.
3. In HubSpot findest du die übertragenen Datensätze unter Kontakte → Custom Objects bzw. direkt auf dem Kontakt-Datensatz unter den zugeordneten Objekten.

💡 Tipp: Über den verknüpften persönlichen Link kannst du in HubSpot-E-Mails einen personalisierten Call-to-Action setzen oder Workflows aufbauen, die auf dem Teilnahmestatus basieren.

‍

Fehlerbehebung

Die Verbindung schlägt fehl

Die Verbindung mit HubSpot konnte nicht hergestellt werden. Stelle sicher, dass dein Access Token die für deinen Anwendungsfall benötigten Scopes enthält (siehe Schritt 1). Diese kannst du in HubSpot unter Einstellungen → Integrationen → Private Apps → deine App → Scopes prüfen und ergänzen.

HubSpot ist als Import-Quelle nicht auswählbar

Stelle sicher, dass die App-Verbindung sowohl auf Workspace- als auch auf Event-Ebene aktiviert ist (Schritt 3).

HubSpot erscheint beim Konten-Import nicht als Quelle

Der Konten-Import nutzt dieselbe HubSpot-Verbindung wie der Kontakt-Import. Stelle sicher, dass HubSpot auf Mandanten-Ebene mit gültigem Access Token verbunden ist (Schritt 2) und der Token die Lese-Scopes crm.lists.read, crm.objects.contacts.read und crm.schemas.contacts.read enthält.

Eventdaten werden nicht nach HubSpot übertragen

Prüfe, ob die Marketing-Events-Synchronisation in der App-Verbindung aktiviert ist (Schritt 2) und ob der Access Token die Scopes crm.objects.marketing_events.read, crm.objects.marketing_events.write und crm.objects.contacts.write enthält. Die Übertragung erfolgt erst ab einer neuen Buchung oder Statusänderung – bereits vor der Aktivierung erfasste Teilnehmer werden nicht rückwirkend übertragen.

Persönliche Event-Links erscheinen nicht in HubSpot

Custom Objects setzen einen HubSpot-Enterprise-Tarif voraus. Prüfe ausserdem, ob die Funktion Custom Objects aktiviert ist und der Token die Custom-Object-Scopes (crm.schemas.custom.*, crm.objects.custom.*) enthält.

Die Verbindung war funktionsfähig, bricht aber plötzlich ab

Verwendest du einen rotierenden Token, ist dieser vermutlich rotiert worden. Aktualisiere den Token in Oniva unter App-Verbindungen. Für eine unterbrechungsfreie Verbindung empfehlen wir einen statischen Token.