Webhooks-API

Run in Postman

Die Webhooks-API ermöglicht es Ihnen, Events zu abonnieren, die in einem HubSpot-Account auftreten, bei dem Ihre Integration installiert ist. Anstatt einen API-Aufruf vorzunehmen, wenn ein Event in einem verknüpften Account stattfindet, kann HubSpot eine HTTP-Anfrage an einen Endpunkt senden, den Sie konfigurieren. Sie können abonnierte Events in den Einstellungen Ihrer App oder mithilfe der unten aufgeführten Endpunkte konfigurieren. Webhooks können skalierbarer sein als ein regelmäßiges Abfragen auf Änderungen, insbesondere für Apps mit einer großen Installationsbasis. Für die Verwendung der Webhooks-API ist Folgendes erforderlich:

Sie müssen eine HubSpot-App für die Verwendung von Webhooks einrichten, indem Sie die Events abonnieren, über die Sie informiert werden möchten, und eine URL angeben, um diese Benachrichtigungen zu senden. Weitere Informationen zur Erstellung einer App finden Sie in der Dokumentation der Voraussetzungen.
Sie müssen einen öffentlich verfügbaren und sicheren (HTTPS)-Endpunkt für diese URL bereitstellen, der die in dieser Dokumentation angegebenen Webhook-Payloads verarbeiten kann.

Webhooks werden für eine HubSpot-App eingerichtet, nicht für einzelne Accounts. Alle Accounts, die Ihre App installieren, indem Sie den OAuth-Prozess durchlaufen, abonnieren deren Webhook-Abonnements. Sie können CRM-Objekt-Events abonnieren, die Kontakte, Unternehmen, Deals, Tickets, Produkte und Einzelposten sowie Konversationen-Events umfassen.

Bitte beachten:

Sie können auch Webhooks in einer privaten App verwalten. In privaten Apps können Webhook-Einstellungen nur in den Einstellungen innerhalb Ihrer privaten App und derzeit nicht über die API bearbeitet werden können.
Um Konversationen-Webhooks zu abonnieren, benötigen Sie Zugriff auf die Konversationen-Postfach- und Nachrichten-APIs, die sich derzeit in der Beta-Phase befindet.

Bereiche

Um Webhooks zum Abonnieren von CRM-Events verwenden zu können, muss Ihre App so konfiguriert werden, dass sie den zugeordneten Bereich erfordert, der dem CRM-Objekttyp entspricht, den Sie abonnieren möchten. Wenn Sie beispielsweise Kontakt-Events abonnieren möchten, müssen Sie den Bereich crm.objects.contacts.read anfragen.

Wenn Sie Abonnements in den Einstellungen Ihrer öffentlichen App erstellen, werden Sie aufgefordert, den erforderlichen Bereich im Bereich Neue Webhook-Abonnements erstellen hinzuzufügen, bevor Sie die Erstellung Ihres Abonnements abschließen.
Wenn Sie ein Abonnement erstellen, indem Sie eine POST-Anfrage an den Endpunkt /webhooks/v3/{appId}/subscriptions durchführen, enthält die Antwort einen Fehler, der den Namen des Bereichs angibt, den Sie in den Einstellungen der Benutzeroberfläche Ihrer öffentlichen App konfigurieren müssen.
Wenn Ihre App bereits Webhooks verwendet, können Sie keine Bereiche entfernen, die für aktive Webhook-Abonnements erforderlich sind, ohne die Abonnements zuvor zu pausieren und zu entfernen.
Sie können die erforderlichen Bereiche für jeden Webhook-Abonnementtyp in der folgenden Tabelle überprüfen.

Weitere Informationen zu Bereichen und zum Einrichten der Autorisierungs-URL für Ihre App finden Sie in der OAuth-Dokumentation.

Webhook-Einstellungen

Bevor Sie Ihre Webhook-Abonnements einrichten, müssen Sie eine URL angeben, an die diese Benachrichtigungen gesendet werden. Befolgen Sie die Anweisungen in den folgenden Abschnitten, um zu erfahren, wie Sie vollständig Abonnements für Ihre App konfigurieren.

Bitte beachten:

Webhook-Einstellungen können bis zu fünf Minuten zwischengespeichert werden. Wenn Sie Änderungen an der Webhook-URL, den Gleichzeitigkeitsbeschränkungen oder den Abonnementeinstellungen vornehmen, kann es bis zu fünf Minuten dauern, bis Ihre Änderungen wirksam werden.
HubSpot legt eine Gleichzeitigkeitsbeschränkung von 10 Anfragen fest, wenn Abonnement-Event-Daten gesendet werden, die mit einem Account verknüpft sind, der Ihre App installiert hat. Diese Gleichzeitigkeitsbeschränkung ist die maximale Anzahl laufender Anfragen, die HubSpot gleichzeitig versucht. Jede Anfrage kann bis zu 100 Events enthalten.

Einstellungen in Ihrem Entwickler-Account verwalten

Sie können Ihre URL und Ihre Event-Steuerungsbeschränkung über die Konfigurationsseite Ihrer App in Ihrem Entwickler-Account verwalten:

Gehen Sie in Ihrem Entwickler-Account zu Ihrem App-Dashboard.
Klicken Sie auf den Namen der App, für die Sie Webhooks einrichten möchten.

Gehen Sie im Menü der Seitenleiste links zu Webhooks.
Geben Sie im Feld Ziel-URL die URL ein, an die HubSpot eine POST-Anfrage sendet, wenn Events ausgelöst werden.
Verwenden Sie die Einstellung Event-Steuerung, um die maximale Anzahl von Evenrts festzulegen, die HubSpot zu senden versucht.

Klicken Sie auf Speichern.

Einstellungen über API verwalten

Sie können die folgenden Endpunkte und Ihren Entwickler-API-Schlüssel verwenden, um die Webhook-Einstellungen für eine App programmgesteuert zu konfigurieren. Um alle Webhook-Einstellungen anzuzeigen, die derzeit für eine App konfiguriert sind, führen Sie eine GET-Anfrage an webhooks/v3/{appId}/settings durch. Sie müssen die App-ID in der Anfrage angeben, die Sie unter dem Namen der App in Ihrem App-Dashboard oder auf der Registerkarte Authentifizierung in den Einstellungen Ihrer App finden. Das Einstellungen-Objekt enthält die folgenden Felder:

Feld	Description
`webhookUrl`	Die URL, an die HubSpot Webhook-Benachrichtigungen sendet. Diese URL muss über HTTPS bereitgestellt werden.
`maxConcurrentRequests`	Das Gleichzeitigkeitsbeschränkung für die Webhook-URL. Dieser Wert muss eine Zahl größer als fünf sein.

Um Änderungen an diesen Einstellungen vorzunehmen, führen Sie eine PUT-Anfrage an webhooks/v3/{appId}/settings durch und fügen Sie die folgenden Felder in den Anfragetext ein:

Feld	Description
`targetUrl`	Die öffentlich verfügbare URL für HubSpot zum Aufrufen und an die Event-Payloads geliefert werden.
`throttling`	Konfigurieren Sie Webhook-Steuerungsdetails in diesem Objekt. Das Steuerungsobjekt enthält die Felder `period` und `maxConcurrentRequests`.
`period`	Zeitskala für diese Einstellung. Kann entweder `SECONDLY` (pro Sekunde) oder `ROLLING_MINUTE` (pro Minute) sein.
`maxConcurrentRequests`	Die maximale Anzahl von HTTP-Anfragen, die HubSpot innerhalb eines durch `period` festgelegten Zeitraums an Ihre App zu senden versucht.

Ihre Anfrage kann beispielsweise wie folgt aussehen:

// PUT request to https://api.hubapi.com/webhooks/v3/{appId}/settings

{
  "throttling": {
    "period": "SECONDLY",
    "maxConcurrentRequests": 10
  },
  "targetUrl": "https://www.example.com/hubspot/target"
}

Webhook-Abonnements

Nachdem Sie Ihre Webhook-URL und Ihre Event-Steuerungsbeschränkung eingerichtet haben, müssen Sie ein oder mehrere Abonnements erstellen. Webhook-Abonnements teilen HubSpot mit, welche Events Ihre spezifische App erhalten möchten. Abonnements gelten für alle Kunden, die Ihre Integration installiert haben. Dies bedeutet, dass Sie nur einmal festlegen müssen, welche Abonnements Sie benötigen. Nachdem Sie ein Abonnement für eine Anwendung aktiviert haben, beginnt sie automatisch, Webhooks für alle Kunden abzurufen, die Ihre Anwendung installiert haben, und Ihre Integration beginnt, Webhook-Trigger von allen neuen Kunden zu empfangen. Bei allen associationChange-Webhook-Abonnements löst der Webhook zwei Events für beide Seiten der Zuordnung aus.

Wenn Sie zwei Kontakte zuordnen, löst ein Abonnement für contact.associationChange zwei Events aus, die contact 1 to contact 2 und contact 2 to contact 1 darstellen.
Wenn Sie beim Zuordnen eines Unternehmens die zwei Webhook-Abonnements contact.associationChange und company.associationChangehaben, erhalten Sie zwei Events. Diese stellen contact 1 to company 1 und company 1 to contact 1 dar.

Die folgenden Abonnementtypen werden unterstützt und können als Wert für das eventType-Feld beim Erstellen von Abonnements über API verwendet werden:

Abonnementtyp	Erforderlicher Bereich	Beschreibung
`contact.creation`	`crm.objects.contacts.read`	Sie erhalten eine Benachrichtigung, wenn ein Kontakt im Account eines Kunden erstellt wird.
`contact.deletion`	Sie erhalten eine Benachrichtigung, wenn ein Kontakt im Account eines Kunden gelöscht wird.
`contact.merge`	Sie erhalten eine Benachrichtigung, wenn ein Kontakt mit einem anderen zusammengeführt wird.
`contact.associationChange`	Sie erhalten eine Benachrichtigung, wenn bei einem Kontakt eine Zuordnung zwischen sich und einem anderen unterstützten Webhook-Objekt (Kontakt, Unternehmen, Deal, Ticket, Einzelposten oder Produkt) hinzugefügt oder entfernt wurde.
`contact.restore`	Sie erhalten eine Benachrichtigung, wenn ein gelöschter Kontakt wiederhergestellt wird.
`contact.privacyDeletion`	Sie erhalten eine Benachrichtigung, wenn ein Kontakt aus Datenschutzschutzgründen gelöscht wird.
`contact.propertyChange`	Sie erhalten eine Benachrichtigung, wenn eine bestimmte Eigenschaft für einen Kontakt im Account eines Kunden geändert wird.
`company.creation`	`crm.objects.companies.read`	Sie erhalten eine Benachrichtigung, wenn ein Unternehmen im Account eines Kunden erstellt wird.
`company.deletion`	Sie erhalten eine Benachrichtigung, wenn ein Unternehmen im Account eines Kunden gelöscht wird.
`company.propertyChange`	Sie erhalten eine Benachrichtigung, wenn eine bestimmte Eigenschaft für ein Unternehmen im Account eines Kunden geändert wird.
`company.associationChange`		Sie erhalten eine Benachrichtigung, wenn bei einem Unternehmen eine Zuordnung zwischen sich und einem anderen unterstützten Webhook-Objekt (Kontakt, Unternehmen, Deal, Ticket, Einzelposten oder Produkt) hinzugefügt oder entfernt wurde.
`company.restore`		Sie erhalten eine Benachrichtigung, wenn ein gelöschtes Unternehmen wiederhergestellt wird.
`company.merge`		Sie erhalten eine Benachrichtigung, wenn ein Unternehmen mit einem anderen zusammengeführt wird.
`deal.creation`	`crm.objects.deals.read`	Sie erhalten eine Benachrichtigung, wenn ein Deal im Account eines Kunden erstellt wird.
`deal.deletion`	Sie erhalten eine Benachrichtigung, wenn ein Deal im Account eines Kunden gelöscht wird.
`deal.associationChange`	Sie erhalten eine Benachrichtigung, wenn bei einem Deal eine Zuordnung zwischen sich und einem anderen unterstützten Webhook-Objekt (Kontakt, Unternehmen, Deal, Ticket, Einzelposten oder Produkt) hinzugefügt oder entfernt wurde.
`deal.restore`	Sie erhalten eine Benachrichtigung, wenn ein gelöschter Deal wiederhergestellt wird.
`deal.merge`	Sie erhalten eine Benachrichtigung, wenn ein Deal mit einem anderen zusammengeführt wird.
`deal.propertyChange`	Sie erhalten eine Benachrichtigung, wenn eine bestimmte Eigenschaft für einen Deal im Account eines Kunden geändert wird.
`ticket.creation`	`tickets`	Sie erhalten eine Benachrichtigung, wenn ein Ticket im Account eines Kunden erstellt wird.
`ticket.deletion`	Sie erhalten eine Benachrichtigung, wenn ein Ticket im Account eines Kunden gelöscht wird.
`ticket.propertyChange`	Sie erhalten eine Benachrichtigung, wenn eine bestimmte Eigenschaft für ein Ticket im Account eines Kunden geändert wird.
`ticket.associationChange`		Sie erhalten eine Benachrichtigung, wenn bei einem Ticket eine Zuordnung zwischen sich und einem anderen unterstützten Webhook-Objekt (Kontakt, Unternehmen, Deal, Ticket, Einzelposten oder Produkt) hinzugefügt oder entfernt wurde.
`ticket.restore`		Sie erhalten eine Benachrichtigung, wenn ein gelöschtes Ticket wiederhergestellt wird.
`ticket.merge`		Sie erhalten eine Benachrichtigung, wenn ein Ticket mit einem anderen zusammengeführt wird.
`product.creation`	`e-commerce`	Sie erhalten eine Benachrichtigung, wenn ein Produkt im Account eines Kunden erstellt wird.
`product.deletion`	Sie erhalten eine Benachrichtigung, wenn ein Produkt im Account eines Kunden gelöscht wird.
`product.restore`	Sie erhalten eine Benachrichtigung, wenn ein gelöschtes Produkt wiederhergestellt wird.
`product.merge`	Sie erhalten eine Benachrichtigung, wenn ein Produkt mit einem anderen zusammengeführt wird.
`product.propertyChange`	Sie erhalten eine Benachrichtigung, wenn ein bestimmtes Produkt für ein beliebiges Produkt im Account eines Kunden geändert wird.
`line_item.creation`	Sie erhalten eine Benachrichtigung, wenn ein Artikel im Account eines Kunden erstellt wird.
`line_item.deletion`	Sie erhalten eine Benachrichtigung, wenn ein Artikel im Account eines Kunden gelöscht wird.
`line_item.associationChange`	Sie erhalten eine Benachrichtigung, wenn bei einem Produkt/Artikel eine Zuordnung zwischen sich und einem anderen unterstützten Webhook-Objekt (Kontakt, Unternehmen, Deal, Ticket, Einzelposten oder Produkt) hinzugefügt oder entfernt wurde.
`line_item.restore`	Sie erhalten eine Benachrichtigung, wenn ein gelöschter Artikel wiederhergestellt wird.
`line_item.merge`	Sie erhalten eine Benachrichtigung, wenn ein Artikel mit einem anderen zusammengeführt wird.
`line_item.propertyChange`	Sie erhalten eine Benachrichtigung, wenn eine bestimmte Eigenschaft für einen Artikel im Account eines Kunden geändert wird.

Die folgenden Konversationen-Abonnementtypen stehen Ihnen zum Abonnieren zur Verfügung, wenn Sie die Conversations-Postfach- und Nachrichten-API verwenden, die sich derzeit in der Beta-Phase befindet:

Abonnementtyp	Bereich	Beschreibung
`conversation.creation`	`conversations.read`	Sie erhalten eine Benachrichtigung, wenn ein neuer Thread in einem Account erstellt wird.
`conversation.deletion`	Sie erhalten eine Benachrichtigung, wenn ein Thread in einem Account archiviert oder vorläufig gelöscht wird.
`conversation.privacyDeletion`	Sie erhalten eine Benachrichtigung, wenn ein Thread in einem Account dauerhaft gelöscht wird.
`conversation.propertyChange`	Sie erhalten eine Benachrichtigung, wenn eine Eigenschaft in einem Thread geändert wurde.
`conversation.newMessage`	Sie erhalten eine Benachrichtigung, wenn eine neue Nachricht in einem Thread empfangen wurde.

Für Abonnements von Eigenschaftsänderungen müssen Sie angeben, für welche Eigenschaft Sie benachrichtigt werden möchten: Sie können mehrere Abonnements von Eigenschaftsänderungen angeben. Wenn der Account eines Kunden nicht über die Eigenschaft verfügt, die Sie in einem Abonnement angeben, erhalten Sie keine Webhooks von diesem Kunden für diese Eigenschaft. Bestimmte Eigenschaften sind für Abonnements von CRN-Eigenschaftsänderungen nicht verfügbar. Diese Eigenschaften sind:

num_unique_conversion_events
hs_lastmodifieddate

Wenn Sie die Conversations-Postfach- und Nachrichten-API verwenden, derzeit in der Beta-Phase, sind die folgenden Eigenschaften verfügbar:

assignedTo: Der Konversationsthread wurde neu zugewiesen oder nicht zugewiesen. Wenn der Thread neu zugewiesen wurde, ist der propertyValue eine Akteur-ID in der Webhooks-Payload. Wenn er nicht zugewiesen wird, ist er leer.
status: Der Status des Konversationsthreads hat sich geändert. In den Webhooks-Payload ist der propertyValue entweder OPEN oder CLOSED.
isArchived: Der Konversationsthread wurde wiederhergestellt. Der propertyValue in der Webhooks-Payload ist immer FALSE.

Abonnements in Ihrem Entwickler-Account erstellen

Sie können Webhook-Abonnements in Ihrem HubSpot-Entwickler-Account erstellen.

Gehen Sie in Ihrem HubSpot-Entwickler-Account zum Apps-Dashboard.
Klicken Sie auf den Namen einer App.
Gehen Sie im Menü der Seitenleiste links zu Webhooks.
Klicken Sie auf Abonnement erstellen.
Klicken Sie im rechten Bereich auf das Dropdown-Menü Welche Objekttypen und wählen Sie die Objekte aus, für die Sie ein Abonnement erstellen möchten.
Klicken Sie auf das Dropdown-Menü Welche Events beobachten? und wählen Sie die Event-Typen aus.

Wenn Sie ein Abonnement für Eigenschaftsänderungs-Events erstellen, klicken Sie auf das Dropdown-Menü Welche Eigenschaften? und wählen Sie die Eigenschaften aus, auf die überwacht werden soll.

Klicken Sie auf Abonnieren.

Das Abonnement wird in Ihren Webhooks-Einstellungen angezeigt. Neue Abonnements werden in einem pausierten Zustand erstellt, daher müssen Sie das Abonnement aktivieren, damit Webhooks Folgendes senden können:

Bewegen Sie den Mauszeiger im Abschnitt Event-Abonnements über den Objekttyp und klicken Sie auf Abonnements anzeigen.
Aktivieren Sie das Kontrollkästchen neben dem Event und klicken Sie dann im Tabellen-Header auf Aktivieren.

Abonnements über API erstellen

Sie können mithilfe der folgenden Endpunkte programmgesteuert Abonnements erstellen. Sie müssen Ihren Entwickler-API-Schlüssel verwenden, wenn Sie Anfragen an diese Endpunkte stellen. Ein Abonnementobjekt kann die folgenden Felder enthalten:

Feld	Description
`id`	Eine Nummer, die die eindeutige ID eines Abonnements darstellt.
`createdAt`	Der Zeitpunkt in Millisekunden, zu dem dieses Abonnement erstellt wurde.
`createdBy`	Die Benutzer-ID, die dem Benutzer zugeordnet ist, der das Abonnement erstellt hat.
`active`	Dies zeigt an, ob das Abonnement aktiviert ist und aktiv Benachrichtigungen auslöst. Der Wert kann `true` oder `false` sein.
`eventType`	Der Typ des Abonnements. Die Tabelle am Anfang dieses Abschnitts enthält die verfügbaren Abonnementtypen.
`propertyName`	Der Name der Eigenschaft, für die das Abonnement auf Änderungen überwacht. Dies wird nur für Abonnementtypen für Eigenschaftsänderungen benötigt.

Abonnements abrufen

Um die Liste der Abonnements abzurufen, führen Sie eine GET-Anfrage an webhooks/v3/{appId}/subscriptions durch. Die Antwort ist ein Array von Objekten, die Ihre Abonnements darstellen. Jedes Objekt enthält Informationen zum Abonnement wie die ID, Erstellungsdatum, Typ und Angabe, ob es derzeit aktiv ist oder nicht. Eine Antwort könnte beispielsweise so aussehen:

// Example GET request to https://api.hubapi.com/webhooks/v3/{appId}/subscriptions

[
  {
    "id": 25,
    "createdAt": 1461704185000,
    "createdBy": 529872,
    "eventType": "contact.propertyChange",
    "propertyName": "lifecyclestage",
    "active": false
  },
  {
    "id": 59,
    "createdAt": 1462388498000,
    "createdBy": 529872,
    "eventType": "company.creation",
    "active": false
  },
  {
    "id": 108,
    "createdAt": 1463423132000,
    "createdBy": 529872,
    "eventType": "deal.creation",
    "active": true
  }
]

Ein neues Abonnement erstellen

Um ein neues Abonnement zu erstellen, führen Sie eine POST-Anfrage an webhooks/v3/{appId}/subscriptions durch. Im Anfragetext können Sie die folgenden Felder einfügen:

Feld	Description
`eventType`	Der Typ des Abonnements.
`propertyName`	Der Name der Eigenschaft, für die das Abonnement auf Änderungen überwacht. Dies wird nur für Abonnementtypen für Eigenschaftsänderungen benötigt.
`active`	Dies zeigt an, ob das Abonnement aktiviert ist und aktiv Benachrichtigungen auslöst. Der Wert kann `true` oder `false` sein.

Sie müssen nicht id, createdAt oder createdBy einschließen, da diese Felder automatisch festgelegt werden. Ihr Anfragetext kann beispielsweise wie folgt aussehen:

// Example POST request to https://api.hubapi.com/webhooks/v3/{appId}/subscriptions

{
  "eventType": "company.propertyChange",
  "propertyName": "companyname",
  "active": false
}

Der eventType muss ein gültiger Abonnementtyp wie im Abschnitt oben definiert sein und der propertyName muss ein gültiger Eigenschaftsname sein. Wenn ein Kunde keine Eigenschaft definiert hat, die diesem Wert entspricht, erhalten Sie bei diesem Abonnement keine Benachrichtigungen.

Ein Abonnement aktualisieren

Um ein Abonnement zu aktivieren oder zu pausieren, führen Sie eine PUT-Anfrage an webhooks/v3/{appId}/subscriptions/{subscriptionId} durch. Schließen Sie im Anfragetext Folgendes ein:

Feld	Description
`active`	Dies zeigt an, ob das Abonnement aktiviert ist und aktiv Benachrichtigungen auslöst. Der Wert kann `true` oder `false` sein.

Ein Abonnement löschen

Um ein Abonnement zu löschen, führen Sie eine DELETE-Anfrage an webhooks/v3/{appId}/subscriptions/{subscriptionId} durch.

Webhook-Payloads

Der Endpunkt unter der Ziel-URL, die Sie in den Webhooks Ihrer App angeben, erhält POST-Anfragen, die JSON-formatierte Daten von HubSpot enthalten. Um sicherzustellen, dass die Anfragen, die Sie auf Ihrem Webhook-Endpunkt erhalten, tatsächlich von HubSpot stammen, füllt HubSpot einen X-HubSpot-Signatur-Header mit einem SSHA-256-Hash aus, der mithilfe des Client-Geheimnisses Ihrer App in Kombination mit Details der Anfrage erstellt wurde. Erfahren Sie mehr über die Validierung von Anfragesignaturen. Verwenden Sie die folgenden Tabellen, um Details zu Feldern anzuzeigen, die in der Payload enthalten sein können.

Feld	Description
`objectId`	Die ID des Objekts, das erstellt, geändert oder gelöscht wurde. Bei Kontakten ist das die Kontakt-ID, bei Unternehmen die Unternehmens-ID, bei Deals die Deal-ID, und bei Konversationen die Thread-ID.
`propertyName`	Dies wird nur für Eigenschaftsänderungsabonnements gesendet und ist der Name der Eigenschaft, die geändert wurde.
`propertyValue`	Dies wird nur für Eigenschaftsänderungsabonnements gesendet und stellt den neuen Wert dar, der für die Eigenschaft festgelegt ist, die die Benachrichtigung ausgelöst hat.
`changeSource`	Die Quelle der Änderung. Dies kann eine der Änderungsquellen sein, die in Verläufen von Kontakteigenschaften angezeigt werden.
`eventId`	Die ID des Events, das diese Benachrichtigung ausgelöst hat. Es ist nicht gewährleistet, dass dieser Wert eindeutig ist.
`subscriptionId`	Die ID des Abonnements, das eine Benachrichtigung über das Event ausgelöst hat.
`portalId`	Die HubSpot-Account-ID des Kunden, in der das Event aufgetreten ist.
`appId`	Die ID Ihrer Anwendung. Dies wird in Fällen verwendet, wenn Sie mehrere Anwendungen haben, die auf dieselbe Webhook-URL verwiesen.
`occurredAt`	Wann dieses Event aufgetreten ist, als Millisekunden-Zeitstempel.
`eventType`	Der Typ des Events, für das diese Benachrichtigung ist. Überprüfen Sie dazu die Liste der unterstützten Abonnementtypen oben im Abschnitt zu Webhooks-Abonnements.
`attemptNumber`	Beginnend mit 0, der wievielte Versuch dies ist, Ihren Service über dieses Event zu benachrichtigen. Wenn Ihr Service eine Zeitüberschreitung oder wie unter Erneute Versuche unten beschriebenen eine Fehlermeldung verursacht, versucht HubSpot, die Benachrichtigung erneut zu senden.
`messageId`	Dies wird nur angezeigt, wenn ein Webhook auf neue Nachrichten zu einem Thread überwacht. Es ist die ID der neuen Nachricht.
`messageType`	Dies wird nur angezeigt, wenn ein Webhook auf neue Nachrichten zu einem Thread überwacht. Es stellt den Typ der Nachricht dar, die Sie senden. Dieser Wert kann entweder `MESSAGE` oder `COMMENT` sein.

Feld	Description
`primaryObjectId`	Die ID des Gewinners der Zusammenführung, also des Datensatzes, der nach der Zusammenführung verbleibt. Auf der HubSpot-Benutzeroberfläche für das Zusammenführen ist dies der Datensatz auf der rechten Seite.
`mergedObjectIds`	Ein Array von IDs, die die Datensätze darstellen, die mit dem Zusammenführungsgewinner zusammengeführt werden. Auf der HubSpot-Benutzeroberfläche für das Zusammenführen ist dies der Datensatz auf der linken Seite.
`newObjectId`	Die ID des Datensatzes, der als Ergebnis der Zusammenführung erstellt wird. Dies ist getrennt von `primaryObjectId`, da in einigen Fällen aufgrund der Zusammenführung ein neuer Datensatz erstellt wird.
`numberOfPropertiesMoved`	Eine Ganzzahl, die angibt, wie viele Eigenschaften während der Zusammenführung übertragen wurden.

Feld	Description
`associationType`	Der Typ der Zuordnung. Folgende Typen gibt es: `CONTACT_TO_COMPANY` `CONTACT_TO_DEAL` `CONTACT_TO_TICKET` `CONTACT_TO_CONTACT` `COMPANY_TO_CONTACT` `COMPANY_TO_DEAL` `COMPANY_TO_TICKET` `COMPANY_TO_COMPANY` `DEAL_TO_CONTACT` `DEAL_TO_COMPANY` `DEAL_TO_LINE_ITEM` `DEAL_TO_TICKET` `DEAL_TO_DEAL` `TICKET_TO_CONTACT` `TICKET_TO_COMPANY` `TICKET_TO_DEAL` `TICKET_TO_TICKET` `LINE_ITEM_TO_DEAL`
`fromObjectId`	Die ID des Datensatzes, von dem aus die Zuordnungsänderung vorgenommen wurde.
`toObjectId`	Die ID des sekundären Datensatzes im Zuordnungs-Event.
`associationRemoved`	Ein boolescher Wert, der Folgendes darstellt: `true`: Der Webhook wurde durch Entfernen einer Zuordnung ausgelöst. `false`: Der Webhook wurde durch Erstellen einer Zuordnung ausgelöst.
`isPrimaryAssociation`	Ein boolescher Wert, der Folgendes darstellt: `true`: Der sekundäre Datensatz ist die primäre Zuordnung des Datensatzes, von dem aus die Zuordnungsänderung vorgenommen wurde. `false`: Der Datensatz ist nicht die primäre Zuordnung des Datensatzes, von dem aus die Zuordnungsänderung vorgenommen wurde. Bitte beachten: Wenn Sie eine primäre Zuordnungsinstanz zwischen zwei Objektdatensätzen erstellen, wird auch die entsprechende nicht primäre Zuordnung erstellt. Dies kann zu zwei Webhook-Nachrichten führen.

//
[
  {
    "objectId": 1246965,
    "propertyName": "lifecyclestage",
    "propertyValue": "subscriber",
    "changeSource": "ACADEMY",
    "eventId": 3816279340,
    "subscriptionId": 25,
    "portalId": 33,
    "appId": 1160452,
    "occurredAt": 1462216307945,
    "eventType": "contact.propertyChange",
    "attemptNumber": 0
  },
  {
    "objectId": 1246978,
    "changeSource": "IMPORT",
    "eventId": 3816279480,
    "subscriptionId": 22,
    "portalId": 33,
    "appId": 1160452,
    "occurredAt": 1462216307945,
    "eventType": "contact.creation",
    "attemptNumber": 0
  }
]

Wie oben gezeigt, sollten Sie eigentlich ein Array von Objekten in einer einzigen Anfrage erhalten. Die Batch-Größe kann variieren, liegt aber unter 100 Benachrichtigungen. HubSpot sendet mehrere Benachrichtigungen, wenn innerhalb eines kurzen Zeitraums sehr viele Events aufgetreten sind. Wenn Sie beispielsweise neue Kontakte abonniert haben und ein Kunde eine große Anzahl von Kontakten importiert, sendet HubSpot Ihnen die Benachrichtigungen für diese importierten Kontakte batchweise und nicht einen pro Anfrage. HubSpot gibt keine Gewährleistung, dass Sie diese Benachrichtigungen in der Reihenfolge erhalten, in der sie aufgetreten ist. Verwenden Sie die occurredAt-Eigenschaft für jede Benachrichtigung, um zu ermitteln, wann das Event aufgetreten ist, das die Benachrichtigung ausgelöst hat. HubSpot gibt ebenfalls keine Gewährleistung, dass Sie nur eine einzelne Benachrichtigung für ein Event erhalten. Obwohl dies nur selten vorkommen sollte, ist es möglich, dass HubSpot Ihnen ein und dieselbe Benachrichtigung mehrmals sendet.

Datenschutzkonforme Kontaktlöschungen

HubSpot-Benutzer haben die Möglichkeit, einen Kontaktdatensatz dauerhaft zu löschen, um Datenschutzgesetze einzuhalten. Erfahren Sie mehr über die Durchführung einer DSGVO-konformen Löschung. Sie können den Abonnementtyp contact.privacyDeletion abonnieren, um Webhook-Benachrichtigungen zu erhalten, wenn ein Benutzer eine datenschutzkonforme Kontaktlöschung durchführt. Benachrichtigungen zu Löschungen aus Datenschutzgründen weisen einige spezielle Verhaltensweisen auf:

Eine Löschung aus Datenschutzgründen löst auch das Event der Kontaktlöschung aus, sodass Sie zwei Benachrichtigungen erhalten, wenn Sie beide Events abonniert haben.
Diese Benachrichtigungen werden nicht unbedingt in einer bestimmten Reihenfolge oder im selben Batch von Nachrichten gesendet. Sie müssen die Objekt-ID verwenden, um die separaten Nachrichten abzugleichen.

Sicherheit

Um sicherzustellen, dass die Anfragen, die Sie auf Ihrem Webhook-Endpunkt erhalten, tatsächlich von HubSpot stammen, füllt HubSpot einen X-HubSpot-Signatur-Header mit einem SSHA-256-Hash der Verkettung des App-Geheimnisses für Ihre Anwendung und dem Anfragetext, den HubSpot sendet. Um diese Signatur zu verifizieren, verketten Sie das App-Geheimnis Ihrer Anwendung und den nicht-geparsten Anfragetext der Anfrage, die Sie verarbeiten, und rufen Sie einen SHA-256-Hash des Ergebnisses ab. Vergleichen Sie resultierenden Hash mit dem Wert der X-HubSpot-Signature. Wenn diese Werte übereinstimmen, wird dadurch verifiziert, dass diese Anforderung von HubSpot stammt. Oder die Anfrage kam von jemand anderem, der Ihr App-Geheimnis kennt. Es ist wichtig, diesen Wert geheim zu halten. Wenn diese Werte nicht übereinstimmen, wurde diese Anfrage möglicherweise während des Transfers manipuliert, oder jemand spooft Webhook-Benachrichtigungen an Ihren Endpunkt. Erfahren Sie mehr über die Validierung von Signaturanfragen.

Erneute Versuche

Wenn bei Ihrem Service Probleme bei der Datenverarbeitung zu irgendeinem Zeitpunkt auftreten, versucht HubSpot, diese Benachrichtigungen bis zu 10 Mal erneut zu senden. HubSpot versucht es in den folgenden Fällen erneut:

Verbindung fehlgeschlagen: HubSpot kann eine http-Verbindung mit der angegebenen Webhook-URL nicht öffnen.
Timeout: Ihr Service benötigt länger als fünf Sekunden, um eine Antwort zurück an einen Batch an Benachrichtigungen zu senden.
Fehlercodes: Ihr Service antwortet mit einem beliebigen HTTP-Statuscode (4xx oder 5xx).

Benachrichtigungen werden bis zu 10 Mal erneut versucht. Diese erneuten Versuche werden mit wechselnden Verzögerungen zwischen den Anfragen über die nächsten 24 Stunden verteilt. Bei einzelnen Benachrichtigungen wird etwas Randomisierung angewendet, um zu verhindern, dass eine große Anzahl erneuter Versuche zum exakt gleichen Zeitpunkt gleichzeitig fehlschlägt.

Beschränkungen

POSTAnfragen, die HubSpot über Ihre Webhook-Abonnements an Ihren Dienst sendet, werden nicht auf die API-Ratenbeschränkungen Ihrer App angerechnet. Sie können maximal 1000 Abonnements pro Anwendung erstellen. Wenn Sie versuchen, mehr Sie zu erstellen, erhalten Sie einen Statuscode 400 Bad Request mit dem folgenden Text:

//
{
  "status": "error",
  "message": "Couldn't create another subscription. You've reached the maximum number allowed per application (1000).",
  "correlationId": "2c9beb86-387b-4ff6-96f7-dbb486c00a95",
  "requestId": "919c4c84f66769e53b2c5713d192fca7"
}

Account & Einstellungen

App-Verwaltung

Authentifizierung

Automatisierung

CMS

Kommunikationseinstellungen

Konversationen

CRM

Veranstaltungen

Dateien

Marketing

Zeitplaner

Webhooks

Run in Postman

Bitte beachten:

Bereiche

Webhook-Einstellungen

Bitte beachten:

Einstellungen in Ihrem Entwickler-Account verwalten

Einstellungen über API verwalten

Webhook-Abonnements

Abonnements in Ihrem Entwickler-Account erstellen

Abonnements über API erstellen

Abonnements abrufen

Ein neues Abonnement erstellen

Ein Abonnement aktualisieren

Ein Abonnement löschen

Webhook-Payloads

Datenschutzkonforme Kontaktlöschungen

Sicherheit

Erneute Versuche

Beschränkungen

Run in Postman

​Bitte beachten:

​Bereiche

​Webhook-Einstellungen

​Bitte beachten:

​Einstellungen in Ihrem Entwickler-Account verwalten

​Einstellungen über API verwalten

​Webhook-Abonnements

​Abonnements in Ihrem Entwickler-Account erstellen

​Abonnements über API erstellen

​Abonnements abrufen

​Ein neues Abonnement erstellen

​Ein Abonnement aktualisieren

​Ein Abonnement löschen

​Webhook-Payloads

​Datenschutzkonforme Kontaktlöschungen

​Sicherheit

​Erneute Versuche

​Beschränkungen

Bitte beachten:

Bereiche

Webhook-Einstellungen

Bitte beachten:

Einstellungen in Ihrem Entwickler-Account verwalten

Einstellungen über API verwalten

Webhook-Abonnements

Abonnements in Ihrem Entwickler-Account erstellen

Abonnements über API erstellen

Abonnements abrufen

Ein neues Abonnement erstellen

Ein Abonnement aktualisieren

Ein Abonnement löschen

Webhook-Payloads

Datenschutzkonforme Kontaktlöschungen

Sicherheit

Erneute Versuche

Beschränkungen