Webhooks-API

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

​

Bereiche

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

​

Webhook-Einstellungen

​

Einstellungen 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

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

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

• num_unique_conversion_events
• hs_lastmodifieddate

• 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

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

• 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

​

Abonnements abrufen

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

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

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

​

Ein Abonnement aktualisieren

​

Ein Abonnement löschen

​

Webhook-Payloads

//
[
  {
    "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
  }
]

​

Datenschutzkonforme Kontaktlöschungen

• 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

​

Erneute Versuche

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

​

Beschränkungen

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