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

Um Webhooks zum Abonnieren von CRM-Events verwenden zu können, muss Ihre App so konfiguriert werden, dass der crm.objects.contacts.read-Bereich erforderlich ist. Ihre App muss so konfiguriert werden, dass der conversations.read-Bereich erforderlich ist, um Konversationen-Events zu abonnieren.

Sie müssen diese Bereiche einrichten, bevor Sie ein Webhook-Abonnement erstellen können. 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 crm.objects.contacts.read- oder conversations.read-Bereich erst entfernen, wenn Sie alle Webhook-Abonnements von Ihrer App entfernt haben.

Bevor Sie Ihre Webhook-Abonnements einrichten, müssen Sie eine URL angeben, an die diese Benachrichtigungen gesendet werden. Sie können auch die Beschränkung im Rahmen der Event-Steuerung, also die Anzahl der gleichzeitigen Anforderungen, die Ihr Endpunkt verarbeiten kann, anpassen.

Diese Steuerungsbeschränkung ist eine Gleichzeitigkeitsbeschränkung, sodass, sobald eine Antwort auf eine Anfrage vorliegt, die gesamten aktiven Anfragen um eine reduziert werden und eine andere Anfrage gesendet werden kann. Wenn Sie beispielsweise ein Limit von 1 Anfrage pro 10 Sekunden haben, wartet HubSpot, wenn 1 Anfrage gesendet wird, auf eine Antwort oder 10 Sekunden lang, bevor eine weitere Anfrage gesendet wird, je nachdem, was zuerst eintritt.

Das Festlegen dieser Beschränkung hilft HubSpot 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 das Limit mehr als einige Sekunden lang erreicht ist. Dies führt zu Benachrichtigungsverzögerungen. 
• 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.

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

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:

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:

Ihre Anfrage kann beispielsweise wie folgt aussehen:

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.

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

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: 

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. 

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

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:

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:

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:

Sie müssen nicht id, createdAt oder createdBy einschließen, da diese Felder automatisch festgelegt werden.

Ihr Anfragetext kann beispielsweise wie folgt aussehen: 

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.

Schließen Sie im Anfragetext Folgendes ein:

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

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.

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.

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.

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. 

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.

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: