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.
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.
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.
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.
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:
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
| Zeitskala für diese Einstellung. Kann entweder |
maxConcurrentRequests
| Die maximale Anzahl von HTTP-Anfragen, die HubSpot innerhalb eines durch |
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:
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 derpropertyValue
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 derpropertyValue
entwederOPEN
oderCLOSED
.isArchived
: Der Konversationsthread wurde wiederhergestellt. DerpropertyValue
in der Webhooks-Payload ist immerFALSE
.
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:
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 |
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. |
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:
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 |
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.
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 |
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.
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 |
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 |
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:
|
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:
|
isPrimaryAssociation
| Ein boolescher Wert, der Folgendes darstellt:
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. |
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.
POST
Anfragen, 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:
Vielen Dank, dass Sie Ihr Feedback mit uns geteilt haben.