Erstellen von Webhooks zur Interaktion mit Drittanbietersystemen

Direktzugriff: Admin Center > Apps und Integrationen > Webhooks > Webhooks

Ein Webhook sendet beim Auftreten einer Aktivität in Zendesk Support eine HTTP-Anforderung an eine bestimmte URL. Sie können zum Beispiel einen Webhook so konfigurieren, dass er Anforderungen sendet, wenn ein Benutzer gelöscht oder ein neues Ticket erstellt wird.

In der Webentwicklung werden Webhooks in der Regel verwendet, um ein Verhalten in einem anderem System zu bewirken. Webhooks können beispielsweise folgende Aufgaben ausführen:

Ihr Team in Slack benachrichtigen, wenn ein dringendes Ticket erstellt wird
Ihrem Dokumentationsteam nach dem Lösen eines Tickets Ticketdetails in Asana zur Verfügung stellen
Ihren eigenen Backend-Dienst über ein wichtiges Ticketereignis benachrichtigen

Webhooks können nur von Administratoren oder Agenten in einer angepassten Rolle mit entsprechenden Berechtigungen erstellt werden. Testkonten sind auf maximal 10 Webhooks und 60 Aufrufe pro Minute beschränkt.

In diesem Beitrag werden folgende Themen behandelt:

Übersicht über Webhooks
Erstellen eines Webhooks
Testen eines Webhooks

Übersicht über Webhooks

Es gibt zwei Möglichkeiten, einen Webhook mit einer Aktivität in Zendesk Support zu verbinden:

Abonnieren Sie den Webhook für ein oder mehrere Zendesk-Ereignisse. Verwenden Sie diese Verbindungsmethode, um Anforderungen auf Grundlage von Organisations-, Benutzer-, Agentenverfügbarkeits-, Help-Center- oder Community-Aktivitäten zu senden. Eine Liste der unterstützten Ereignistypen finden Sie unter Webhook event types in der API-Referenz.
Verbinden Sie den Webhook mit einem Auslöser oder einer Automatisierung. Verwenden Sie diese Verbindungsmethode, um Anforderungen auf Grundlage von Ticketaktivitäten zu senden.

Ein Webhook, der ein Zendesk-Ereignis abonniert hat, kann nicht mit einem Auslöser oder einer Automatisierung verbunden werden. Ebenso kann ein Webhook, der mit einem Auslöser oder einer Automatisierung verbunden ist, keine Zendesk-Ereignisse abonnieren. Die Verbindungsmethode eines bestehenden Webhooks kann nicht geändert werden.

Wichtig: Zendesk bemüht sich nach Kräften, Webhook-Ereignisse für Aktionen möglichst in Echtzeit an Benutzer zu übermitteln. Trotzdem können unter Umständen Verzögerungen auftreten.

Abonnieren von Zendesk-Ereignissen

Ein Webhook, der ein oder mehrere Zendesk-Ereignisse abonniert hat, sendet Anforderungen immer mit der HTTP-Methode POST. Die Anforderung enthält eine JSON-Nutzlast mit den Ereignisdaten. Die HTTP-Methode oder die Nutzlast für die Anforderung kann nicht geändert werden. Weitere Informationen zu Nutzlast-Schemas für Ereignisse finden Sie unter Webhook event types in der API-Referenz.

Verbinden mit Auslösern oder Automatisierungen

Wenn ein Webhook mit einem Auslöser oder einer Automatisierung verbunden ist, können Sie die HTTP-Methode, das Format und den Inhalt der Webhook-Anforderungen anpassen. Die HTTP-Methode und das Format des Anforderungstexts wählen Sie bei der Erstellung des Webhooks aus. Webhooks, die mit einem Auslöser oder einer Automatisierung verbunden sind, unterstützen die folgenden Formate für den Anforderungstext:

JSON
XML
Formularcodierte Inhalte

Sie definieren den Inhalt der Anforderung, wenn Sie den Webhook mit einem Auslöser oder einer Automatisierung verbinden. Bei Webhooks, die die HTTP-Methode POST, PUT oder PATCH mit einem JSON- oder XML-Anforderungsformat verwenden, ist der Inhalt die Nutzlast der Anforderung. Webhooks, die andere HTTP-Methoden oder Formate verwenden, enthalten keine Nutzlast für die Anforderung. Stattdessen können Sie angepasste URL-Parameter als Array aus zwei Schlüssel-Wert-Strings hinzufügen. Beim Definieren der Nutzlast oder URL-Parameter der Anforderung können Sie einen der verfügbaren Inhaltsplatzhalter verwenden, um Ticketdaten in die Anforderung einzufügen.

Die Nutzlast oder URL-Parameter der Anforderung müssen kleiner sein als 256 KB.

Ändern der Reihenfolge von Webhooks und Neuversuche

Wenn ein Ereignis, ein Auslöser oder eine Automatisierung einen Webhook aufruft, wird der Webhook-Job in die Warteschlange gestellt, aber nicht sofort ausgeführt. Da Webhook-Aufträge unabhängig voneinander ausgeführt werden, lässt sich die Reihenfolge, in der sie abgearbeitet werden, nicht festlegen.

Webhook-Anforderungen werden automatisch bis zu dreimal wiederholt, wenn der Endpunkt bestimmte HTTP-Antwortcodes zurückgibt. Anders als Ziele werden Webhooks nicht nach drei fehlgeschlagenen Aufrufen in Folge deaktiviert. Weitere Informationen und Beispiele zu Wiederholungsszenarien finden Sie in unserer Entwicklerdokumentation unter Monitoring webhooks (Englisch).

Erstellen eines Webhooks

Sie erstellen Webhooks im Admin Center.

So erstellen Sie einen Webhook

Klicken Sie in der Seitenleiste des Admin Centers auf Apps und Integrationen und dann auf Webhooks > Webhooks.
Klicken Sie auf Webhook erstellen.
- Um den Webhook für ein oder mehrere Zendesk-Ereignisse zu abonnieren, wählen Sie Zendesk-Ereignisse und dann im Dropdownmenü einen oder mehrere Ereignistypen.
- Um den Webhook mit einem Auslöser oder einer Automatisierung zu verbinden, wählen Sie Auslöser oder Automatisierung.
Klicken Sie auf Next.
Geben Sie einen Namen und eine Beschreibung für den Webhook ein.
Geben Sie die Endpunkt-URL für die Integration mit dem Dienst oder System des Drittanbieters ein. Weitere Informationen finden Sie unter Webhook-Endpunkte.
Beim Einrichten eines Webhooks zur Integration mit einem Drittanbieter müssen Sie unter Umständen dessen Dokumentation zurate ziehen.
Wählen Sie die Anfragemethode und das Anfrageformat des Webhooks aus.
Wählen Sie die Authentifizierungsmethode für den Webhook aus und geben Sie alle weiteren erforderlichen Daten ein. Weitere Informationen finden Sie unter Authentifizieren eines Webhooks.
(Optional) Klicken Sie auf Kopfzeile hinzufügen und füllen Sie die Felder Name der Kopfzeile und Wert aus. Bei Bedarf können Sie auf Weitere Kopfzeile hinzufügen klicken und bis zu vier weitere Kopfzeilen hinzufügen. Weitere Informationen finden Sie unter Angepasste Webhook-Kopfzeilen.
Hinweis: Nehmen Sie keine vertraulichen Informationen in Ihre angepassten Kopfzeilen auf.
(Optional) Klicken Sie auf Webhook testen, um sicherzustellen, dass er wie erwartet funktioniert.
Klicken Sie auf Webhook estellen, um den Webhook zu erstellen.
Bei Auslöser- und Automatisierungs-Webhooks müssen Sie den Webhook mit einem Auslöser oder einer Automatisierung verbinden. Weitere Informationen finden Sie unter Verbinden eines Webhooks mit einem Auslöser oder einer Automatisierung. Kehren Sie nach dem Verbinden des Auslösers oder der Automatisierung zur Seite Webhook erstellen zurück und klicken Sie auf Einrichtung abschließen.

Nachdem Sie den Webhook erstellt haben, können Sie die entsprechenden Details, Abonnements und Aktivitäten auf der Seite „Webhooks“ im Admin Center anzeigen. Weitere Informationen finden Sie unter Verwalten von Webhooks.

Webhook-Endpunkte

Webhooks senden Anforderungen an die Endpunkt-URL, die Sie bei der Erstellung angeben. Die Endpunkt-URL weist das folgende Format auf: https://www.yourdomain.com/path.

Die Verwendung von sicherem HTTP (HTTPS) ist nicht zwingend erforderlich, wird aber empfohlen. Eine sichere Endpunkt-URL ermöglicht die Authentifizierung sowie die sichere Übertragung von Daten.

Angepasste Webhook-Kopfzeilen

Angepasste Kopfzeilen bieten eine Möglichkeit, zusätzliche Informationen in die von Ihrem Webhook gesendete Anfrage aufzunehmen, und können die Verbindung zu einigen Drittanbieterdiensten erleichtern, die spezielle Anforderungen an Webhook-Kopfzeilen stellen. Für angepasste Kopfzeilen gelten folgende Anforderungen und Einschränkungen:

Angepasste Kopfzeilen können nur in Verbindung mit einer sicheren Endpunkt-URL (HTTPS) verwendet werden.
Fügen Sie keine Authentifizierungsdaten oder andere vertrauliche Informationen in angepasste Kopfzeilen ein. Verwenden Sie stattdessen die unterstützten Authentifizierungsmethoden.
Der Name der Kopfzeile muss eindeutig sein und darf nicht mehr als 128 Zeichen enthalten. Neben allen US ASCII-Zeichen werden folgende Sonderzeichen unterstützt: !, #, $, %, &, ', *, +, -, ., ^, _, `, | und ~.
Der Wert der Kopfzeile kann bis zu 1.000 Zeichen lang sein und alle US ASCII-Zeichen von 0x20 bis 0x7E enthalten.

Authentifizieren eines Webhooks

Wenn Ihr Webhook mit einem sicheren Endpunkt integriert ist, haben Sie drei Möglichkeiten, den Webhook und die von ihm gesendeten Daten zu authentifizieren. Bei Bedarf können Sie die Authentifizierungsanforderungen des Endpunkts in der Dokumentation des Drittanbieters nachschlagen oder die für den Endpunkt geeignete Authentifizierungsmethode gemeinsam mit einem Entwickler Ihres Teams bestimmen.

Nicht erforderlich: Es ist keine Authentifizierung konfiguriert oder erforderlich.
API-Schlüssel: Verwenden Sie zur Authentifizierung des Webhooks einen API-Schlüssel.
Standardauthentifizierung Verwenden Sie zur Authentifizierung des Webhooks einen Benutzernamen und ein Kennwort.
Inhaber-Token: Verwenden Sie zur Authentifizierung des Webhooks ein OAuth-Zugriffstoken.

Wenn Ihre Entwickler weitere Informationen zur Authentifizierung von Webhooks brauchen, verweisen Sie sie auf den Beitrag Webhook security and authentication (Englisch).

Für zusätzliche Sicherheit können Sie auch die Signatur des Webhooks überprüfen. Weitere Informationen finden Sie unter Verifying webhook authenticity (Englisch).

Verbinden eines Webhooks mit einem Auslöser oder einer Automatisierung

Zum Aufrufen eines Auslöser- und Automatisierungs-Webhooks müssen Sie den Webhook zuerst mit einem Auslöser oder einer Automatisierung verbinden. Die Auslöser und Automatisierungen geben an, unter welchen Voraussetzungen der Webhook aufgerufen werden soll.

So verbinden Sie einen Webhook mit einem Support-Auslöser

Klicken Sie in der Seitenleiste des Admin Centers auf Objekte und Regeln und dann auf Business-Regeln > Auslöser.
Erstellen Sie einen neuen Auslöser, oder setzen Sie den Mauszeiger auf das Symbol „Optionen“ () eines vorhandenen Auslösers und klicken Sie auf Bearbeiten.
Klicken Sie unter Aktionen auf Aktion hinzufügen. Wählen Sie Webhook benachrichtigen und klicken Sie dann auf Ihren Webhook.
Geben Sie die Anforderungs-Nutzlast oder URL-Parameter des Webhooks ein, je nach dem Anforderungsformat des Webhooks. Nutzlast oder Parameter müssen kleiner sein als 256 KB.
Klicken Sie auf Speichern.

So verbinden Sie einen Webhook mit einer Support-Automatisierung

Klicken Sie in der Seitenleiste des Admin Centers auf Objekte und Regeln und dann auf Business-Regeln > Automatisierungen.
Erstellen Sie eine neue Automatisierung oder bearbeiten Sie eine vorhandene Automatisierung, indem Sie den Mauszeiger auf das Symbol „Optionen“ () setzen und auf Bearbeiten klicken.
Klicken Sie unter Diese Aktionen durchführen auf das Symbol „Aktion hinzufügen“ (). Wählen Sie Benachrichtigungen: Webhook benachrichtigen und klicken Sie dann auf Ihren Webhook.
Geben Sie die Anforderungs-Nutzlast oder URL-Parameter des Webhooks ein, je nach dem Anforderungsformat des Webhooks. Nutzlast oder Parameter müssen kleiner sein als 256 KB.
Klicken Sie auf Einreichen.

Testen eines Webhooks

Im Admin Center haben Sie die Möglichkeit, den Webhook mit verschiedenen Ereignisquellen und Anforderungen zu testen. Sie können einen vorhandenen Webhook für den Test auswählen, aber auch einen Webhook testen, den Sie gerade erstellen oder bearbeiten.

So testen Sie einen Webhook

Klicken Sie in der Seitenleiste des Admin Centers auf Apps und Integrationen und dann auf Webhooks > Webhooks.
Wählen Sie den Webhook in der Liste aus, klicken Sie auf sein Optionsmenü () und wählen Sie Webhook testen.
Wählen Sie im Bereich Webhook testen das Ereignis aus, das Sie testen möchten. Hierbei handelt es sich um eine Beispielanforderung, die Sie verwenden können, um Ihre Endpunkt-URL zu testen.
Geben Sie die Details Ihrer Testanforderung – Anforderungstext, Parameter oder Header – ein.
Klicken Sie auf Test senden. Die Antwort wird im Bereich unter der Testanforderung angezeigt.