Zum Hauptinhalt springen
Letzte Änderung: 8. Oktober 2025
Mit benutzerdefinierten Events können Sie Events definieren und nachverfolgen, die für Ihr Unternehmen spezifisch sind, z. B. Events auf Ihrer Website oder in einer App. Sie können Events konfigurieren, um Informationen in Eigenschaften zu speichern, die Sie dann in allen HubSpot-Tools nutzen können. Um Daten von benutzerdefinierten Events an HubSpot zu senden, müssen Sie zunächst das Event definieren. Dies ist ähnlich wie bei benutzerdefinierten CRM-Objekten, bei denen Sie zunächst das benutzerdefinierte Objekt definieren müssen, bevor Sie einzelne Datensätze für dieses Objekt erstellen können. Eine Event-Definition enthält Details wie Metadaten, CRM-Objektzuordnungen und Eigenschaften. Im Folgenden erfahren Sie mehr über das Erstellen und Verwalten von Event-Definitionen mithilfe der API. Um zu erfahren, wie Sie Event-Definitionen erstellen können, ohne die API zu verwenden, sehen Sie sich diesen Artikel in der Wissensdatenbank von HubSpot an.

​
Eine Event-Definition erstellen

Um das benutzerdefinierte Event-Schema zu erstellen, führen Sie eine POST-Anfrage an events/v3/event-definitions durch. Fügen Sie in den Anfragetext Definitionen für Ihr Event-Schema ein, einschließlich Label, Name, CRM-Objektzuordnungen und benutzerdefinierte Eigenschaften. Der folgende Anforderungstext enthält ein einfaches Beispiel für eine Event-Definition: 
{
  "label": "My event label",
  "name": "unique_event_name",
  "description": "An event description that helps users understand what the event tracks.",
  "primaryObject": "COMPANY",
  "propertyDefinitions": [
    {
      "name": "choice-property",
      "label": "Choice property",
      "type": "enumeration",
      "options": [
        {
          "label": "Option 1",
          "value": "1"
        },
        {
          "label": "Option 2",
          "value": "2"
        }
      ]
    },
    {
      "name": "string-property",
      "label": "String property",
      "type": "string"
    }
  ],
  "includeDefaultProperties": true
}
Wenn Sie Event-Abschlüsse automatisch mit Datensätzen eines bestimmten CRM-Objekttyps verknüpfen möchten, können Sie ein customMatchingId in Ihre POST-Anfrage aufnehmen. Definieren Sie in diesem Feld ein primaryObjectRule-Objekt mit zwei Feldern: die eindeutige Objekteigenschaft, die Sie zuvor als targetObjectPropertyName eingerichtet haben, und eine der Eigenschaften, die Sie in den propertyDefinitions aus Ihrer Event-Definition definiert haben. Der folgende Anforderungstext gibt beispielsweise einecustomMatchingId an, die mit einem CRM-Objekteigenschaftsnamen von "unique_object_property" und dem Event-Eigenschaftsnamen von "string_property" übereinstimmt: 
{
  "label": "My event label",
  "name": "unique_event_name",
  "description": "An event description that helps users understand what the event tracks.",
  "primaryObject": "COMPANY",
  "propertyDefinitions": [
    {
      "name": "string-property",
      "label": "String property",
      "type": "string"
    }
  ],
  "customMatchingId": {
    "primaryObjectRule": {
      "targetObjectPropertyName": "unique_object_property",
      "eventPropertyName": "event_property"
    }
  }
}
Eine vollständige Liste der verfügbaren Parameter für den Anforderungstext finden Sie in der folgenden Tabelle:
ParameterTypBeschreibung
labelZeichenfolgeDas für Menschen lesbare Label des Events, das in HubSpot angezeigt wird (bis zu 100 Zeichen). Lange Labels können in bestimmten Teilen der HubSpot-Benutzeroberfläche abgeschnitten werden.
nameZeichenfolgeDer eindeutige, interne Name des Events, mit dem Sie über die API auf das Event verweisen können. Wenn kein Wert angegeben wird, generiert HubSpot automatisch einen Wert auf der Grundlage des Labels.
  • Diese Eigenschaft kann nach dem Erstellen der Event-Definition nicht mehr geändert werden.
  • Diese Eigenschaft darf nur Kleinbuchstaben, Zahlen, Unterstriche und Bindestriche enthalten (bis zu 50 Zeichen).
  • Das erste Zeichen muss ein Buchstabe sein.
descriptionZeichenfolgeDie Beschreibung des Events, die in HubSpot angezeigt wird.
primaryObjectZeichenfolge: Der Typ des CRM-Objekts, dem die Event-Daten zugeordnet werden. Event-Abschlüsse werden in den CRM-Datensätzen dieses Objekttyps angezeigt. Kann entweder "CONTACT" (Standard), "COMPANY", "DEAL", "TICKET" oder "<CUSTOM_OBJECT_NAME>" sein. Diese kann nicht mehr geändert werden, nachdem die Event-Definition erstellt wurde.
propertyDefinitionsArrayZusätzlich zu den standardmäßigen Event-Eigenschaften von HubSpot können Sie dieses Array einschließen, um benutzerdefinierte Event-Eigenschaften (bis zu 50) zu definieren. Fügen Sie für jedes Eigenschaftsobjekt die folgenden Felder hinzu:
  • name: der interne Name der Eigenschaft, den Sie beim Senden von Event-Daten über die API verwenden.
  • label: das Label der Eigenschaft in der App.
  • type: der Eigenschaftstyp. Standardmäßig wird string verwendet.
  • options: Für Eigenschaften des Typs enumeration definiert dieses Array die verfügbaren Werte. Muss sowohl label als auch value für jede Option enthalten.
  • description: Text, der die Eigenschaft beschreibt.
customMatchingIdObjektAls Alternative zur Aufnahme der objectId des Zielobjekts in die Daten zu Event-Abschlüssen definiert dieses optionale Feld eine Regel zur automatischen Verknüpfung von Event-Abschlüssen mit Datensätzen des angegebenen CRM-Objekttyps. Dazu wird der Wert einer Eigenschaft in den Event-Daten mit dem Wert einer eindeutigen Eigenschaft im Zielobjekt abgeglichen. Dieses Objekt muss ein verschachteltes primaryObjectRule-Objekt enthalten, das wiederum zwei Felder enthalten muss:
  • targetObjectPropertyName: eine Zeichenfolge, die den Namen der eindeutigen Eigenschaft auf dem Ziel-CRM-Objekt angibt, die für den Abgleich verwendet werden soll.
  • eventPropertyName: eine Zeichenfolge, die den Namen der Eigenschaft in den benutzerdefinierten Event-Daten angibt, der für den Abgleich verwendet werden soll.
includeDefaultPropertiesBoolesches FeldEin optionales Feld, das angibt, ob das Event den Satz der Standard-Event-Eigenschaften enthalten soll. Wenn kein Wert angegeben wird, wird dieses Feld automatisch auf true festgelegt.

​
Event-Eigenschaften

Benutzerdefinierte Eigenschaften von Events werden verwendet, um Informationen über einzelne benutzerdefinierte Event-Abschlüsse zu speichern. Diese Eigenschaften sollten verwendet werden, wenn sie für das Senden von Event-Abschlüssen geeignet sind, aber sie sind nicht erforderlich, damit ein Event-Abschluss gültig ist. Für jede Event-Definition bietet HubSpot einen Standardsatz von 32 Eigenschaften. Darüber hinaus können Sie bis zu 50 benutzerdefinierte Eigenschaften pro Event-Eigenschaft erstellen. Eigenschaften können einer der folgenden Typen sein:
  • bool: eine Eigenschaft, die einen booleschen Wert erhält. Werte müssen als true oder false angegeben werden.
  • date: Eine Eigenschaft, die ein Datum empfängt, das einen bestimmten Tag, einen bestimmten Monat und ein bestimmtes Jahr darstellt. Werte müssen in UTC-Zeit angegeben werden und können als ISO 8601-Zeichenfolgen oder EPOCH-Zeitstempel in Millisekunden (z. B. Mitternacht UTC) formatiert werden.
  • datetime: Eine Eigenschaft, die Epochen-Millisekunden- oder ISO8601-Werte empfängt, die einen Zeitstempel darstellen.
  • enumeration: Eine Eigenschaft mit vordefinierten Optionen. Fügen Sie bei der Erstellung dieses Eigenschaftstyps ein options-Array ein, um die verfügbaren Werte festzulegen.
  • number: eine Eigenschaft, die numerische Werte mit bis zu einer Dezimalstelle empfängt.
  • string: eine Eigenschaft, die Klartext-Zeichenfolgen empfängt. Wenn der Eigenschaftsname die Wörter url, referrer oder link enthält, kann der Eigenschaftswert bis zu 1024 Zeichen lang sein. Ansonsten können die Eigenschaftswerte bis zu 256 Zeichen lang sein.
Im Folgenden erfahren Sie mehr über die standardmäßigen Event-Eigenschaften von HubSpot, wie Sie neue Eigenschaften für bestehende Events definieren und wie Sie bestehende benutzerdefinierte Event-Eigenschaften aktualisieren.

​
Standard-Event-Eigenschaften von HubSpot

  • hs_asset_description
  • hs_asset_type
  • hs_browser
  • hs_campaign_id
  • hs_city
  • hs_country
  • hs_device_name
  • hs_device_type
  • hs_element_class
  • hs_element_id
  • hs_element_text
  • hs_language
  • hs_link_href
  • hs_operating_system
  • hs_operating_version
  • hs_page_content_type
  • hs_page_id
  • hs_page_title
  • hs_page_url
  • hs_parent_module_id
  • hs_referrer
  • hs_region
  • hs_screen_height
  • hs_screen_width
  • hs_touchpoint_source
  • hs_tracking_name
  • hs_user_agent
  • hs_utm_campaign
  • hs_utm_content
  • hs_utm_medium
  • hs_utm_source
  • hs_utm_term

​
Neue Eigenschaften definieren

Um eine neue Eigenschaft für ein bestehendes benutzerdefiniertes Event zu definieren, führen Sie eine POST-Anfrage an events/v3/event-definitions/{eventName}/property durch. Fügen Sie im Anfragetext die Definition für Ihre Eigenschaft ein. 
{
  "name": "property-name",
  "label": "Property name",
  "type": "enumeration",
  "options": [
    {
      "label": "label",
      "value": "value"
    }
  ]
}
Bei der Benennung Ihrer Eigenschaften sollten Sie Folgendes beachten:
  • Sobald Sie eine Eigenschaft erstellt haben, kann der Name der Eigenschaft nicht mehr geändert werden.
  • Der Name darf nur Kleinbuchstaben, Zahlen, Unterstriche und Bindestriche enthalten.
  • Das erste Zeichen des Eigenschaftsnamens muss ein Buchstabe sein.
  • Der Eigenschaftsname und das Label können jeweils bis zu 50 Zeichen lang sein.
  • Wenn kein Eigenschaftsname angegeben wird, wird dieser automatisch anhand des Labels der Eigenschaft generiert.
  • Lange Label können in bestimmten Teilen der HubSpot-Benutzeroberfläche abgeschnitten werden.

​
Bestehende benutzerdefinierte Eigenschaften aktualisieren

Um eine bestehende Eigenschaft eines benutzerdefinierten Events zu aktualisieren, führen Sie eine PATCH-Anfrage an events/v3/event-definitions/{eventName}/property durch. Die einzigen Felder, die für eine Eigenschaft aktualisiert werden können, sind die Felder label, description und options für Aufzählungseigenschaften.

​
Hinweis:

Um den Typ der Eigenschaft zu ändern, verwenden Sie den DELETE-Endpunkt, um die Eigenschaft zu löschen und mit dem richtigen Typ neu zu erstellen.

​
Eine Eigenschaft löschen

Um eine vorhandene Eigenschaft eines benutzerdefinierten Events zu löschen, führen Sie eine DELETE-Anfrage an events/v3/event-definitions/{eventName}/property/{propertyName} durch. Wenn eine Eigenschaft gelöscht wird, steht sie nicht mehr für die Verwendung in zukünftigen Event-Abschlüssen zur Verfügung. Bei früheren Abschlüssen bleiben die Eigenschaftenwerte erhalten.

​
Ein Event aktualisieren

Um ein bestehendes benutzerdefiniertes Event-Schema zu aktualisieren, führen Sie eine PATCH-Anfrage an events/v3/event-definitions/{eventName} durch. Die einzigen Event-Definitionsfelder, die aktualisiert werden können, sind label und description. 
{
  "label": "Event label",
  "description": "A description of the event"
}

​
Ein Event löschen

Um ein benutzerdefiniertes Event zu löschen, führen Sie eine DELETE-Anfrage an events/v3/event-definitions/{eventName} durch. Wenn Sie ein benutzerdefiniertes Event löschen, wird es aus allen anderen HubSpot-Tools entfernt, die darauf verweisen, z. B. aus Workflows und Berichten.

​
Bitte beachten Sie beim Löschen eines Events Folgendes:

  1. Es werden alle Events für diese Event-Definition gelöscht und können nicht wiederhergestellt werden.
  2. Zuvor gelöschte eventName-Eigenschaften können nicht mehr verwendet werden. Seien Sie also vorsichtig, wenn Sie ein Event löschen.

​
Vorhandene Event-Definitionen abrufen

Um eine einzelne Event-Definition abzurufen, führen Sie eine GET-Anfrage an events/v3/event-definitions/{eventName} durch. Um Event-Definitionen nach bestimmten Kriterien zu durchsuchen, führen Sie eine GET-Anfrage an events/v3/event-definitions durch. Sie können die folgenden Abfrageparameter angeben, um Ihre Suche zu verfeinern:
  • searchString: sucht nach Events, die die angegebenen Zeichen im Feld name enthalten. Die Suche ist nicht unscharf, sondern ist eine naive contains-Suche.
  • after: eine gehashte Zeichenfolge, die in seitenweisen Antworten zum Anzeigen der nächsten Seite der Suchergebnisse bereitgestellt wird.
  • limit: die maximale Anzahl der Ergebnisse, die zurückgegeben werden sollen.
  • includeProperties: ein boolescher Wert, der angibt, ob Event-Eigenschaften in die zurückgegebenen Ergebnisse aufgenommen werden sollen.