Webhooks

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, 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.

 

Bereiche

Um Webhooks verwenden zu können, muss Ihre App so konfiguriert werden, dass der contacts-Bereich erforderlich ist. Dieser Bereich muss eingerichtet werden, bevor Sie ein Webhook-Abonnement erstellen können, entweder über Ihren Entwickler-Account in den Einstellungen, oder bei Verwendung der Webhooks-API zum Konfigurieren von Abonnements. Weitere Informationen zu Bereichen und zum Einrichten der Autorisierungs-URL für Ihre App finden Sie in der OAuth-Dokumentation.

Wenn Ihre App bereits Webhooks verwendet, können Sie den contacts-Bereich erst entfernen, wenn Sie alle Webhook-Abonnements aus Ihrer App entfernt haben.

 

Webhooks-Setup

Hinweis: Webhook-Einstellungen können bis zu fünf Minuten zwischengespeichert werden. Wenn Sie Änderungen an der Webhook-URL, den Ratenbeschränkungen oder den Abonnementeinstellungen vornehmen, kann es bis zu fünf Minuten dauern, bis Ihre Änderungen wirksam werden.

 

Webhook-URL und Ratenbeschränkungen

Bevor Sie Ihre Webhook-Abonnements einrichten, müssen Sie eine URL angeben, an die diese Benachrichtigungen gesendet werden. Darüber hinaus können Sie die Rate abstimmen, mit der Ihr Endpunkt Anfragen verarbeiten kann.

Das Festlegen dieser Ratenbeschränkung hilft Ihnen dabei, Benachrichtigungen so schnell wie möglich zu versenden, ohne Ihre API zu sehr auszulasten.

  • Wenn Sie dieses Limit zu niedrig festlegen, treten möglicherweise Zeitüberschreitungen bei Benachrichtigungen auf, wenn zu viele Benachrichtigungen an Ihre API gesendet werden und deshalb dieses Limit mehr als einige Sekunden lang erreicht ist. Dies führt zu Verzögerungen, bevor Sie Benachrichtigungen erhalten.
  • Wenn Sie dieses Limit zu hoch festlegen, kann dies eine vollständige Ausnutzung der für Ihren Endpunkt verfügbaren Ressourcen zur Folge haben. Dies wiederum kann zu langen Antwortzeiten, Verzögerungen bei Benachrichtigungen oder nicht mehr antwortenden Endpunkten führen.

 

Verwalten über die Benutzeroberfläche

Sie können Ihre URL und die Einstellungen für Ratenbeschränkungen über die Konfigurationsseite Ihrer App in Ihrem Entwickler-Account verwalten:

1. Wählen Sie im Apps-Dashboard die App aus, für die Sie Webhooks einrichten möchten.
app_id_list

2. Wählen Sie das linke Webhooks-Navigationselement aus. Dieser Bildschirm bietet eine Oberfläche zur Festlegung der Ziel-URL und der Event-Steuerungsbeschränkung.

webhook_settings

Verwalten über die API

Diese Endpunkte ermöglichen es Ihnen, programmgesteuert Webhook-Einstellungen für eine App festzulegen. Es wird empfohlen, die Benutzeroberfläche zu verwenden, um Ihre Apps einzurichten. Sie müssen Ihren Entwickler-API-Schlüssel verwenden, wenn Sie Anfragen an diese Endpunkte stellen.

Felder für Einstellungen

Das Einstellungen-Objekt hat die folgenden Felder:

  • webhookUrl – Die URL, mit der wir Webhook-Benachrichtigungen senden. Sie muss über HTTPS bereitgestellt werden.
  • maxConcurrentRequests – Die Gleichzeitigkeitsbeschränkung für diese URL, wie in „Webhook-URL und Gleichzeitigkeitsbeschränkung“ erläutert
Anzeigen von Einstellungen

Der folgende Endpunkt ruft die aktuell für Ihre Anwendung eingerichteten Webhook-Einstellungen auf, sofern vorhanden:

GET https://api.hubapi.com/webhooks/v3/{appId}/settings

Das Ergebnis sieht etwas so aus:

{
  "webhookUrl": "https://testing.com/webhook",
  "maxConcurrentRequests": 20
}

Aktualisieren von Einstellungen

Um diese Einstellungen zu ändern, können Sie den folgenden Endpunkt verwenden:

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

Mit einem Anfragetext wie diesem:

{
  "webhookUrl": "https://testing.com/webhook-modified",
  "maxConcurrentRequests": 25
}
 

Validierung:

  • webhookUrl muss eine gültige URL sein, die über HTTPS bereitgestellt wird.
  • maxConcurrentRequests muss eine Zahl größer als fünf sein.

 

Webhook-Abonnements

Nachdem Sie Ihren Webhook-URl und Ihre Ratenbegrenzungseinstellungen eingerichtet haben, müssen Sie ein oder mehrere Abonnements erstellen. Webhook-Abonnements teilen HubSpot mit, welche Events Ihre spezifische App erhalten möchten. Wir unterstützen derzeit folgende Abonnementtypen:

  • Kontakterstellungen
  • Kontaktlöschungen
  • Datenschutzkonforme Kontaktlöschungen – weitere Informationen dazu finden Sie unten
  • Änderungen an Kontakteigenschaften
  • Unternehmenserstellungen
  • Unternehmenslöschungen
  • Änderungen an Unternehmenseigenschaften
  • Deal-Erstellungen
  • Deal-Löschungen
  • Änderungen an Deal-Eigenschaften

 

Einige Aspekte sollten Sie bei Abonnements beachten:

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 Eigenschaftsänderungen nicht verfügbar. Diese Eigenschaften sind:


Kontakteigenschaften:

  • days_to_close
  • recent_conversion_event_name
  • recent_conversion_date
  • first_conversion_event_name
  • first_conversion_date
  • num_unique_conversion_events
  • num_conversion_events
  • hs_additional_emails

Deal-Eigenschaften:

  • num_associated_contacts

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 zu empfangen, die Ihre Anwendung installiert haben, und Sie erhalten dann automatisch Webhooks von allen neuen Kunden, die Ihre Integration zukünftig installieren.

Es kann eine Verzögerung von bis zu fünf Minuten zwischen dem Erstellen oder Ändern von Abonnements und dem Inkrafttreten von Änderungen vorkommen.

 

Verwalten von Abonnements über die Benutzeroberfläche

Sie können Webhook-Abonnements über Ihren Entwickler-Account erstellen:

  1. Wählen Sie im Entwickler-Apps-Dashboard die App aus, für die Sie Webhooks senden möchten.
  2. Wählen Sie das Navigationselement „Webhook-Abonnements“ aus.
  3. Klicken Sie auf „Abonnement erstellen“.
    webhook_settings
  4. Wählen Sie den Objekttyp (d. h. Kontakt, Unternehmen, Deal) und Event-Typ (d. h. Erstellung, Änderung, Löschung) aus. Hinweis: „Aus Datenschutzgründen gelöscht“ kann nur dann ausgewählt werden, wenn „Kontakte“ der einzige ausgewählte Objekttyp ist.
    create_webhook_subscription
  5. (Optional) Wählen Sie für Eigenschaftsänderungs-Events die fragliche Eigenschaft aus. Hinweis: Sie können auch Eigenschaftsnamen manuell eingeben, sodass Sie benutzerdefinierte Eigenschaften verwenden können.

HINWEIS: Neue Abonnements werden im pausierten Zustand erstellt. Sie müssen das Abonnement aktivieren, damit Webhooks gesendet werden können.

activate_subscription

Verwalten von Abonnements über die API

Diese Endpunkte ermöglichen es Ihnen, programmgesteuert Abonnements zu erstellen. Es gibt nichts in diesen Endpunkten, das Sie nicht über die Benutzeroberfläche erledigen können, und die Benutzeroberfläche ist die bevorzugte Methode zum Einrichten Ihrer App. Sie müssen Ihren Entwickler-API-Schlüssel verwenden, wenn Sie Anfragen an diese Endpunkte stellen.

Abonnementfelder

Ein Abonnement-Objekt hat die folgenden Felder:

  • id – Eine Nummer, die die eindeutige ID eines Abonnements darstellt.
  • createdAt – Wenn dieses Abonnement erstellt wurde, ist dies ein Millisekunden-Zeitstempel.
  • createdBy – Die userId des Benutzers, der dieses Abonnement erstellt hat.
  • enabled – Gibt an, ob dieses Abonnement derzeit aktiv ist und Benachrichtigungen auslöst.
  • subscriptionDetails – Dies beschreibt, welche Arten von Events dieses Abonnement beobachtet
  • subscriptionType – Ein Zeichenfolge, die darstellt, welcher Typ von Abonnement dies ist (wie unter „Abonnement-Types“ unten definiert).
  • propertyName – Nur für Eigenschaftsänderungstypen erforderlich. Der Name der Eigenschaft, die auf Änderungen beobachtet werden soll. Dies kann nur einen einzigen Eigenschaftsname sein.

 

Abonnementtypen

Die EigenschaftsubscriptionType kann einer der folgenden Werte sein:

  • contact.creation – Um benachrichtigt zu werden, wenn ein Kontakt im Account eines Kunden erstellt wird.
  • contact.deletion – Um benachrichtigt zu werden, wenn ein Kontakt im Account eines Kunden gelöscht wird.
  • contact.privacyDeletion – Um benachrichtigt zu werden, wenn ein Kontakt aus Datenschutzschutzgründen gelöscht wird. Weitere Informationen dazu finden Sie unten.
  • contact.propertyChange Um benachrichtigt zu werden, wenn eine bestimmte Eigenschaft für einen Kontakt im Account eines Kunden geändert wird.
  • company.creation – Um benachrichtigt zu werden, wenn ein Unternehmen im Account eines Kunden erstellt wird.
  • company.deletion – Um benachrichtigt zu werden, wenn ein Unternehmen im Account eines Kunden gelöscht wird.
  • company.propertyChange – Um benachrichtigt zu werden, wenn eine bestimmte Eigenschaft für ein Unternehmen im Account eines Kunden geändert wird.
  • deal.creation – Um benachrichtigt zu werden, wenn ein Deal im Account eines Kunden erstellt wird.
  • deal.deletion – Um benachrichtigt zu werden, wenn ein Deal im Account eines Kunden gelöscht wird.
  • deal.propertyChange – Um benachrichtigt zu werden, wenn eine bestimmte Eigenschaft für einen Deal im Account eines Kunden geändert wird.

 

Abonnements abrufen

So rufen Sie die Liste der Abonnements ab:

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

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 aktiviert ist oder nicht. Eine Antwort könnte beispielsweise so aussehen:

// [ { "id": 25, "createdAt": 1461704185000, "createdBy": 529872, "subscriptionDetails": { "subscriptionType": "contact.propertyChange", "propertyName": "lifecyclestage" }, "enabled": true }, { "id": 59, "createdAt": 1462388498000, "createdBy": 529872, "subscriptionDetails": { "subscriptionType": "company.creation" }, "enabled": false }, { "id": 108, "createdAt": 1463423132000, "createdBy": 529872, "subscriptionDetails": { "subscriptionType": "deal.creation" }, "enabled": true } ]
Neues Abonnement erstellen

So erstellen Sie neue Abonnements:

POST https://api.hubapi.com/webhooks/v1/{appId}/subscriptions

Mit einem Anfragetext wie diesem:

// { "subscriptionDetails": { "subscriptionType":"company.propertyChange", "propertyName": "companyname" }, "enabled": false }
Dabei stimmen die Felder in diesem Anfragetext mit den in „Abonnement-Felder“ definierten überein. Mit diesem Endpunkt können Sie jedoch nicht idcreatedAt oder createdBy festlegen, da diese Felder automatisch festgelegt werden.

Validierung:

subscriptionType muss ein gültiger Abonnementtyp wie im Abschnitt „Abonnement-Typen“ oben definiert sein.

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.

enabled muss true oder false sein.

 
Abonnement aktualisieren

Sie können nur die aktivierte Kennzeichnung für ein Abonnement aktualisieren. Dazu können Sie den folgenden Endpunkt verwenden:

PUT https://api.hubapi.com/webhooks/v1/{appId}/subscriptions/{subscriptionId}

Anfragetext:

{ "enabled" : false }

Abonnement löschen

Um ein Abonnement zu löschen, können Sie den folgenden Endpunkt aufrufen:

DELETE https://api.hubapi.com/webhooks/v1/{appId}/subscriptions/{subscriptionId}

 

Webhook-Payloads

Der Endpunkt unter der URL, die Sie in den Webhooks angeben, erhält Anfragen wie die folgende:

Art der Methode: POST

Headers:

Content-Type: Application/Json
X-HubSpot-Signature: {Ein Hash des App-Geheimnisses und Anfragetextes, siehe unten für weitere Informationen.}


Beispiel-Anfragetext:

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

Anfragefelder:

  • objectId : Die ID des Objekts, das erstellt/geändert/gelöscht wurde. Bei Kontakten ist das die vid, bei Unternehmen die companyId, und bei Deals die dealId.
    propertyName : Dies wird nur angezeigt, wenn die Benachrichtigung für eine Eigenschaftsänderung ist. Dies ist der Name der Eigenschaft, die geändert wurde
  • propertyValue : Dies wird nur angezeigt, wenn die Benachrichtigung für eine Eigenschaftsänderung ist. Dies ist der neue Wert, der für diese Eigenschaft, die diese Benachrichtigung ausgelöst hat, festgelegt wurde.
  • changeSource : Die Quelle dieser Änderung. Kann eine der Änderungsquellen sein, die Sie in Verläufen von Kontakteigenschaften finden.
  • eventId : Die eindeutige ID des Events, das diese Benachrichtigung ausgelöst hat.
  • subscriptionId : Die ID des Abonnements, aufgrund dessen wir Ihnen eine Benachrichtigung dieses Events gesendet haben.
  • portalId : Das portalId des Kunden, von der dieses Event stammt.
  • appId : Die ID Ihrer Anwendung. (Im Falle mehrerer Anwendungen wird auf dieselbe Webhook-URL verwiesen.)
  • occurredAt : Wann dieses Event aufgetreten ist, als Millisekunden-Zeitstempel.
  • subscriptionType : Der Typ des Events, für das diese Benachrichtigung ist. Eine der Liste der Abonnementtypen finden Sie oben im Abschnitt „Abonnement-Typen“.
  • attemptNumber : Der wievielte Versuch dies ist, Ihren Service über dieses Event zu benachrichtigen (beginnt mit 0). Wenn Ihr Service eine Zeitüberschreitung oder wie unter „Erneute Versuche” unten beschriebenen eine Fehlermeldung verursacht, versuchen wir, die Benachrichtigung erneut an Ihren Service zu senden.

 

HINWEIS ZUM BATCHING: Wie oben gezeigt, erhalten Sie mehrere Benachrichtigungen in einer einzigen Anfrage. Die Batch-Größe kann variieren, liegt aber unter 100 Benachrichtigungen. Wir senden nur dann 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, senden wir Ihnen die Benachrichtigungen für diese importierten Kontakte batchweise und nicht einzeln pro Anfrage.

HINWEIS ZUR REIHENFOLGE: Wir geben keine Gewährleistung, dass Sie diese Benachrichtigungen in der Reihenfolge erhalten, in der sie aufgetreten ist. Bitte verwenden Sie die occurredAt-Eigenschaft für jede Benachrichtigung, um zu ermitteln, wann die Benachrichtigung aufgetreten ist.

HINWEIS ZUR EINZIGARTIGKEIT: Wir geben 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 wir Ihnen ein und dieselbe Benachrichtigung mehrmals senden.

 

Handhaben von datenschutzkonformen Kontaktlöschungen

HubSpot-Benutzer haben die Möglichkeit, einen Kontaktdatensatz dauerhaft zu löschen, um Datenschutzgesetze einzuhalten. Weitere Informationen zu diesem Feature finden Sie in folgendem Hilfeartikel: https://knowledge.hubspot.com/de/contacts/how-do-i-perform-a-gdpr-compliant-delete-in-hubspot

Sie können den Abonnementtyp contact.privacyDeletion abonnieren, um Webhook-Benachrichtigungen zu erhalten, wenn ein Benutzer eine datenschutzkonforme Kontaktlöschung durchführt.

Hinweis: Benachrichtigungen zu Löschungen aus Datenschutzgründen weisen einige spezielle Verhaltensweisen auf:
  • Eine Löschung aus Datenschutzgründen löst auch das normale contact.delete-Event aus, sodass Sie zwei Benachrichtigungen erhalten, wenn Sie beide Events abonniert haben.
  • Wir geben keine Gewährleistung, dass diese Benachrichtigungen in einer bestimmten Reihenfolge oder im selben Batch von Nachrichten gesendet werden. Sie müssen die objectId verwenden, um die separaten Nachrichten abzugleichen.

 

Sicherheit

Hinweis: Webhooks verwenden die v1-Version des X-HubSpot-Signature-Headers. Auf dieser Seite finden Sie weitere Details zur Validierung dieser Version der Signatur, und auf dieser Seite finden Sie weitere Details zum Validieren von Anfragen im Allgemeinen.

Um sicherzustellen, dass die Anfragen, die Sie auf Ihrem Webhook-Endpunkt erhalten, tatsächlich von HubSpot stammen, füllen wir einen X-HubSpot-Signature-Header mit einem SSHA-256-Hash der Verkettung des App-Geheimnisses für Ihre Anwendung und dem Anfragetext, den wir senden.

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 jemand, 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.

Erneute Versuche

Wenn bei Ihrem Service Probleme bei der Datenverarbeitung zu irgendeinem Zeitpunkt auftreten, versuchen wir, diese Benachrichtigungen bis zu 10 Mal erneut zu senden.

Erneute Versuche werden in den folgenden Fällen durchgeführt:

Verbindung fehlgeschlagen  – Wenn wir keine http-Verbindung mit der angegebenen Webhook-URL öffnen können
Timeout – Wenn Ihr Service länger als 5 Sekunden benötigt, um eine Antwort zurück an einen Batch an Benachrichtigungen zu senden
Fehlercodes – Wenn Ihre Service mit einem beliebigen HTTP-Statuscode (4xx oder 5xx) antwortet

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

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" }

War dieser Artikel hilfreich?
Dieses Formular dient dazu, Feedback zu unserer Entwicklerdokumentation zu sammeln. Wenn Sie uns Ihre Meinung zu HubSpot-Produkten mitteilen möchten, teilen Sie diese bitte im Ideenforum der Community.