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 benutzerdefinierte Objekte: Oniva überträgt persönliche Event-Links als eigene Objekt-Datensätze nach HubSpot (benutzerdefiniertes Objekt "Oniva Participants"), 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 benutzerdefinierte Objekte setzt einen HubSpot-Enterprise-Tarif voraus, da benutzerdefinierte Objekte 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 Integrationen → 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 "Bereiche" und aktiviere die Berechtigungen entsprechend deinem Anwendungsfall (siehe Liste unten).
5. Speichere die App und wechsle zum Tab "Authentifizierung".
6. Klicke auf "Token anzeigen" und anschliessend auf "Kopieren".
7. Füge den Access Token in Oniva unter App-Verbindungen ein (siehe Schritt 2).

Erforderliche Bereiche

Aktiviere mindestens die Bereiche, 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 (benutzerdefinierte Objekte, nur HubSpot Enterprise):

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

👉 Hinweis: Fehlende Bereiche 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. Benutzerdefinierte Objekte: 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 Bereiche deines Access Tokens abgedeckt sein (siehe Schritt 1). Aktivierst du z. B. benutzerdefinierte Objekte, ohne die benutzerdefinierte-Objekte-Bereiche 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 (siehe Segmente in HubSpot).
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 → Objekte → 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 benutzerdefinierte Objekte übertragen

Persönliche Event-Links (individuelle Teilnahme-Links pro Kontakt) werden über ein HubSpot benutzerdefinierte Objekte ü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 (benutzerdefinierte Objekte sind nur in Enterprise-Konten verfügbar).
• Die benutzerdefinierte-Objekte-Bereiche im Access Token (siehe Schritt 1).
• Die Funktion benutzerdefinierte Objekte 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 eine Buchung erstellt wird, überträgt Oniva diese als Datensätze des benutzerdefinierte Objekte 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 → Benutzerdefinierte Objekte 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.

Wo finde ich den persönlichen Link in HubSpot?

Für die Übertragung von persönlichen Links erstellt Oniva in HubSpot benutzerdefinierte Objekte mit der Bezeichnung "Oniva Participant". Dieses Objekt wird erstellt, sobald eine Buchung vorliegt. Damit können beispielsweise Buchungsbestätigungen über automatisierte E-Mails aus HubSpot ausgelöst oder andere Workflows angestossen werden. Bitte beachte, dass aktuell nur automatisierte Marketing-E-Mails (z. B. durch einen Workflow ausgelöst) von HubSpot unterstützt werden.

‍

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 Bereiche enthält (siehe Schritt 1). Diese kannst du in HubSpot unter Einstellungen → Integrationen → Private Apps → deine App → Bereiche 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-Bereiche 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 Bereiche 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

Benutzerdefinierte Objekte setzen einen HubSpot-Enterprise-Tarif voraus. Prüfe ausserdem, ob die Funktion benutzerdefinierte Objekte aktiviert ist und der Token die Custom-Object-Bereiche (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.