> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.de/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhooks-API
export const postmanIcon = ;
# 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](https://developers.hubspot.de/docs).
* 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](/apps/legacy-apps/public-apps/overview) eingerichtet, nicht für einzelne Accounts. Alle Accounts, die Ihre App installieren, indem Sie den [OAuth-Prozess](https://developers.hubspot.de/docs/reference/api/app-management/oauth/tokens#initiate-an-integration-with-oauth-2.0) 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](/apps/legacy-apps/private-apps/create-and-edit-webhook-subscriptions-in-private-apps). 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](/api-reference/conversations-conversations-inbox-&-messages-v3/guide), 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](#webhook-subscriptions) überprüfen.
[Weitere Informationen zu Bereichen](https://developers.hubspot.de/docs/reference/api/app-management/oauth/tokens#initiate-an-integration-with-oauth-2.0#scopes) und zum [Einrichten der Autorisierungs-URL](https://developers.hubspot.de/docs/reference/api/app-management/oauth/tokens#initiate-an-integration-with-oauth-2.0) 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](https://developers.hubspot.de/docs/apps/developer-platform/build-apps/authentication/overview) 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](https://developers.hubspot.de/docs) 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:
```json theme={null}
// 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.associationChange`haben, 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](https://developers.hubspot.de/docs/guides/api/app-management/webhooks/overview) 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](/api-reference/conversations-conversations-inbox-&-messages-v3/guide) 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](/api-reference/conversations-conversations-inbox-&-messages-v3/guide) 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](https://developers.hubspot.de/docs/guides/api/app-management/webhooks/overview#webhook-subscriptions) 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:
```json theme={null}
// 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:
```json theme={null}
// 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](/apps/legacy-apps/authentication/validating-requests).
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](/api-reference/conversations-conversations-inbox-&-messages-v3/guide). |
| `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](https://knowledge.hubspot.com/de/account-management/manage-multiple-hubspot-accounts#check-your-current-account) 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](https://knowledge.hubspot.com/de/records/associate-records#primary-company-information) 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. |
```json theme={null}
//
[
{
"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 o`ccurredAt`-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](https://knowledge.hubspot.com/de/privacy-and-consent/how-do-i-perform-a-gdpr-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.
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](/apps/legacy-apps/authentication/validating-requests).
## 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
`POST`Anfragen, die HubSpot über Ihre Webhook-Abonnements an Ihren Dienst sendet, werden nicht auf die [API-Ratenbeschränkungen Ihrer App](/apps/legacy-apps/api-usage/usage-details) 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:
```json theme={null}
//
{
"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"
}
```
* 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](https://developers.hubspot.de/docs/apps/developer-platform/build-apps/authentication/overview) 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](https://developers.hubspot.de/docs) 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:
```json theme={null}
// 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.associationChange`haben, 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](https://developers.hubspot.de/docs/guides/api/app-management/webhooks/overview) 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](/api-reference/conversations-conversations-inbox-&-messages-v3/guide) 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](/api-reference/conversations-conversations-inbox-&-messages-v3/guide) 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](https://developers.hubspot.de/docs/guides/api/app-management/webhooks/overview#webhook-subscriptions) 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:
```json theme={null}
// 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:
```json theme={null}
// 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](/apps/legacy-apps/authentication/validating-requests).
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](/api-reference/conversations-conversations-inbox-&-messages-v3/guide). |
| `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](https://knowledge.hubspot.com/de/account-management/manage-multiple-hubspot-accounts#check-your-current-account) 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: