So richten Sie einen Zendesk-Webhook für Ticket-Erstellungsereignisse ein

Webhooks sind eines der leistungsstärksten Werkzeuge im Automatisierungsarsenal von Zendesk. Sie ermöglichen es Ihnen, Echtzeit-Benachrichtigungen an externe Systeme zu senden, wenn etwas in Ihrem Helpdesk passiert. Wenn ein Kunde ein neues Ticket einreicht, kann ein Webhook Ihr Team sofort in Slack benachrichtigen, Ihr CRM aktualisieren oder benutzerdefinierte Workflows in Ihren eigenen Anwendungen auslösen.

Das Einrichten eines Zendesk-Webhooks für Ticket-Erstellungsereignisse ist nicht kompliziert, aber es gibt einige wichtige Entscheidungen zu treffen. Diese Anleitung führt Sie durch den gesamten Prozess, von der anfänglichen Konfiguration bis zum Testen und zur Fehlerbehebung.

Was Sie benötigen

Bevor Sie beginnen, stellen Sie sicher, dass Sie Folgendes haben:

• Ein Zendesk Support-Konto im Team-Plan oder höher (Webhooks sind im Essential-Plan nicht verfügbar)
• Administratorzugriff oder eine benutzerdefinierte Rolle mit Webhook-Erstellungsberechtigungen
• Eine Endpunkt-URL, die HTTP-POST-Anfragen empfangen kann (dies könnte ein Dienst wie Zapier, eine benutzerdefinierte API oder eine Webhook-Testseite sein)
• Ein API-Token, wenn Sie die Authentifizierung verwenden möchten (für die Produktion empfohlen)

Testkonten haben einige Einschränkungen: maximal 10 Webhooks und 60 Aufrufe pro Minute. Das ist ausreichend zum Testen, aber Sie sollten ein Upgrade durchführen, bevor Sie mit einer starken Automatisierung live gehen.

Schritt 1: Erstellen Sie den Webhook in Zendesk

Zuerst müssen Sie den Webhook selbst erstellen. Dies definiert, wohin Zendesk Daten sendet und wie es sich authentifiziert.

Navigieren Sie zu Admin Center → Apps und Integrationen → Webhooks. Klicken Sie oben rechts auf Aktionen und wählen Sie dann Webhook erstellen.

Sie sehen ein Formular mit mehreren Feldern zum Konfigurieren:

Name und Beschreibung: Geben Sie Ihrem Webhook einen eindeutigen Namen wie "Neue Ticketbenachrichtigung", damit Sie ihn später identifizieren können. Die Beschreibung ist optional, aber hilfreich, wenn Sie mehrere Webhooks haben.

Endpunkt-URL: Hier sendet Zendesk die Webhook-Daten. Es muss eine gültige HTTPS-URL sein, die POST-Anfragen akzeptieren kann. Zum Testen können Sie einen Dienst wie webhook.site verwenden, um die Payloads anzuzeigen, ohne Ihren eigenen Endpunkt zu erstellen.

HTTP-Methode: Für Ereignisabonnements muss dies POST sein. Wenn Sie stattdessen eine Verbindung zu Triggern herstellen, können Sie GET, POST, PUT, PATCH oder DELETE auswählen, je nachdem, was Ihr Endpunkt erwartet.

Anfrageformat: Für Ereignisabonnements muss dies JSON sein. Trigger-verbundene Webhooks unterstützen auch XML- und formcodierte Formate.

Authentifizierung: Dies wird für die Produktion dringend empfohlen. Zendesk unterstützt drei Methoden:

• API-Schlüssel: Fügt einen benutzerdefinierten Header mit Ihrem Schlüssel hinzu
• Basisauthentifizierung: Benutzername und Passwort, Base64-codiert
• Bearer-Token: OAuth 2.0-Token im Authorization-Header

Sobald Sie alles ausgefüllt haben, klicken Sie unten auf Erstellen. Ihr Webhook wurde nun erstellt, aber noch nicht mit Ereignissen verbunden. Das ist der nächste Schritt.

Schritt 2: Wählen Sie Ihre Verbindungsmethode

Hier müssen Sie eine wichtige Entscheidung treffen. Zendesk bietet zwei Möglichkeiten, Webhooks mit Ticketaktivitäten zu verbinden, und Sie können dies später nicht mehr ändern, ohne den Webhook zu löschen und neu zu erstellen.

Option A: Ereignisabonnement (zen:event-type:ticket.created)

Dieser Ansatz abonniert Ihren Webhook direkt im Zendesk-Ereignisstrom. Wenn ein Ticket erstellt wird, wird Ihr Webhook ausgelöst.

Vorteile:

• Wird garantiert für jedes erstellte Ticket ausgelöst
• Einfache Einrichtung: keine Trigger erforderlich
• Nahezu Echtzeit-Zustellung

Nachteile:

• Feste Payload-Struktur (Sie können nicht anpassen, welche Daten gesendet werden)
• Keine Filterung: Sie erhalten jedes Ticket, sogar Spam
• Muss POST und JSON verwenden

Option B: Trigger-verbundener Webhook

Dieser Ansatz verbindet Ihren Webhook mit einem Zendesk-Trigger. Der Trigger entscheidet anhand von Bedingungen, die Sie definieren, wann er ausgelöst wird.

Vorteile:

• Volle Kontrolle darüber, wann der Webhook ausgelöst wird (bestimmte Gruppen, Prioritäten, Tags)
• Anpassbare Payload mit Zendesk-Platzhaltern
• Kann Rauschen herausfiltern (Spam, Testtickets usw.)

Nachteile:

• Erfordert das Erstellen und Warten eines Triggers
• Etwas komplexere Einrichtung

Welche sollten Sie wählen? Wenn Sie jedes Ticket benötigen und es Ihnen nichts ausmacht, es auf Ihrer Seite zu filtern, verwenden Sie Ereignisabonnements. Wenn Sie nur bestimmte Tickets wünschen (z. B. dringende Probleme oder Tickets von bestimmten Organisationen), verwenden Sie Trigger-verbundene Webhooks.

Schritt 3: Konfigurieren Sie den Trigger (für Trigger-verbundene Webhooks)

Wenn Sie Option B gewählt haben, müssen Sie nun einen Trigger erstellen, der Ihren Webhook aufruft.

Navigieren Sie zu Admin Center → Objekte und Regeln → Trigger. Klicken Sie auf Trigger hinzufügen.

Legen Sie Ihre Bedingungen fest:

Fügen Sie mindestens Folgendes hinzu: Ticket | Ist | Erstellt

Sie können weitere Bedingungen hinzufügen, um zu filtern, welche Tickets den Webhook auslösen:

• Priorität ist hoch oder dringend
• Gruppe ist "Technischer Support"
• Tags enthalten "eskaliert"
• Organisation ist ein bestimmter VIP-Kunde

Fügen Sie die Webhook-Aktion hinzu:

Wählen Sie unter Aktionen im Dropdown-Menü Aktiven Webhook benachrichtigen aus. Wählen Sie den Webhook aus, den Sie in Schritt 1 erstellt haben.

Konfigurieren Sie die JSON-Payload:

Hier definieren Sie, welche Daten an Ihren Endpunkt gesendet werden. Verwenden Sie Zendesk-Platzhalter, um Ticketdaten einzufügen:

{
  "ticket_id": "{{ticket.id}}",
  "subject": "{{ticket.title}}",
  "description": "{{ticket.description}}",
  "requester_email": "{{ticket.requester.email}}",
  "requester_name": "{{ticket.requester.name}}",
  "priority": "{{ticket.priority}}",
  "status": "{{ticket.status}}",
  "group": "{{ticket.group.name}}",
  "assignee": "{{ticket.assignee.name}}",
  "created_at": "{{ticket.created_at}}",
  "tags": "{{ticket.tags}}",
  "url": "{{ticket.link}}"
}

Zendesk ersetzt jeden Platzhalter durch die tatsächlichen Ticketdaten, wenn der Webhook ausgelöst wird. Sie können auch Liquid Markup für bedingte Logik verwenden.

Wichtig: Fügen Sie eine Nullifizierungsbedingung hinzu, um Endlosschleifen zu verhindern. Da der Trigger ausgelöst wird, wenn ein Ticket erstellt wird, und der Webhook das Ticket möglicherweise aktualisiert, benötigen Sie eine Bedingung, die verhindert, dass der Trigger erneut ausgelöst wird. Ein gängiges Muster ist das Hinzufügen eines Tags in Ihrer Webhook-Antwort und das Ausschließen von Tickets mit diesem Tag.

Schritt 4: Testen Sie Ihren Webhook

Bevor Sie sich in der Produktion auf Ihren Webhook verlassen, müssen Sie überprüfen, ob er funktioniert.

Testen Sie über die Webhook-Einstellungen:

Gehen Sie zurück zu Admin Center → Apps und Integrationen → Webhooks. Suchen Sie Ihren Webhook und klicken Sie auf das Drei-Punkte-Menü, dann auf Webhook testen.

Zendesk sendet eine Test-Payload an Ihren Endpunkt. Der Test verwendet ein statisches Signierungsgeheimnis (dGhpc19zZWNyZXRfaXNfZm9yX3Rlc3Rpbmdfb25seQ==), damit Sie die Signaturvalidierung überprüfen können.

Testen Sie mit einem echten Ticket:

Erstellen Sie ein Testticket in Zendesk. Überprüfen Sie Ihren Endpunkt, um Folgendes zu überprüfen:

• Die Anfrage ist angekommen
• Die Payload enthält erwartete Daten
• Authentifizierungsheader sind vorhanden (falls konfiguriert)
• Die Signatur wird validiert (bei Verwendung von HMAC)

Überprüfen Sie die Webhook-Aktivitätsprotokolle:

Zendesk führt 7 Tage lang Protokolle von Webhook-Aufrufen. Sie können über die Webhooks API auf diese zugreifen, um den Zustellungsstatus, Antwortcodes und alle Fehler anzuzeigen.

Verstehen der Webhook-Payload

Wenn Zendesk einen Webhook für ein Ticket-Erstellungsereignis sendet, unterscheidet sich die Payload-Struktur je nach Ihrer Verbindungsmethode.

Ereignisabonnierte Payload

Für direkte Ereignisabonnements folgt die Payload einem festen Schema:

{
  "type": "zen:event-type:ticket.created",
  "account_id": 22129848,
  "id": "cbe4028c-7239-495d-b020-f22348516046",
  "time": "2025-01-08T10:12:07.672Z",
  "zendesk_event_version": "2022-11-06",
  "subject": "zen:ticket:5158",
  "detail": {
    "actor_id": "8447388090494",
    "assignee_id": "8447388090494",
    "brand_id": "8447346621310",
    "created_at": "2025-01-08T10:12:07Z",
    "description": "I need help with my order",
    "id": "5158",
    "is_public": true,
    "organization_id": "8447346622462",
    "priority": "LOW",
    "requester_id": "8447388090494",
    "status": "OPEN",
    "subject": "Order help needed",
    "tags": ["order", "help"],
    "via": { "channel": "web_service" }
  },
  "event": { "meta": { "sequence": { "id": 12345, "position": 1 } } }
}

Zu den Schlüsselfeldern gehören die Ticket-ID, der Betreff, die Beschreibung, die Anforderer-ID, die Priorität, der Status und der Erstellungszeitstempel.

Trigger-verbundene Payload

Für Trigger-verbundene Webhooks ist die Payload das, was Sie in der Trigger-Aktion definiert haben. Sie haben die volle Kontrolle über die Struktur und den Inhalt.

Authentifizierung und Sicherheit

Webhooks können sensible Ticketdaten enthalten, daher ist es wichtig, sie zu sichern.

Authentifizierungsmethoden:

• API-Schlüssel: Fügen Sie einen Header wie X-API-Key: your-secret-key hinzu
• Basisauthentifizierung: Base64-codierter Benutzername:Passwort im Authorization-Header
• Bearer-Token: OAuth 2.0-Stil Authorization: Bearer your-token

HMAC-Signaturüberprüfung:

Zendesk unterstützt HMAC-SHA256-Signaturen, um die Webhook-Authentizität zu überprüfen. Jeder Webhook erhält ein eindeutiges Signierungsgeheimnis. Zendesk signiert jede Anfrage, indem es einen HMAC über den Zeitstempel und den Anfragetext berechnet.

Ihr Endpunkt sollte:

1. Extrahieren Sie die Signatur aus dem x-zendesk-webhook-signature-Header
2. Extrahieren Sie den Zeitstempel aus dem x-zendesk-webhook-signature-timestamp-Header
3. Berechnen Sie die erwartete Signatur mit Ihrem Signierungsgeheimnis
4. Vergleichen Sie mit zeitkonstantem Vergleich, um Timing-Angriffe zu verhindern

Bewährte Methoden:

• Verwenden Sie immer HTTPS-Endpunkte
• Überprüfen Sie Signaturen in der Produktion
• Speichern Sie Signierungsgeheimnisse sicher (nicht in Code-Repositories)
• Implementieren Sie Idempotenz, um doppelte Zustellungen zu verarbeiten
• Geben Sie schnell den Status 200 zurück; verarbeiten Sie bei Bedarf asynchron

Behebung häufiger Probleme

Auch bei sorgfältiger Einrichtung funktionieren Webhooks manchmal nicht wie erwartet. Hier sind die häufigsten Probleme und wie Sie sie beheben können.

Webhook wird nicht ausgelöst:

• Überprüfen Sie die Triggerbedingungen: Werden sie tatsächlich erfüllt?
• Stellen Sie sicher, dass der Trigger aktiv ist (nicht deaktiviert)
• Suchen Sie nach Nullifizierungsbedingungen, die die Ausführung verhindern könnten
• Bestätigen Sie, dass der Webhook-Status "aktiv" ist

Endpunktfehler (4xx, 5xx-Antworten):

• 410 Gone: Ihr Endpunkt hat einen Fehler zurückgegeben; überprüfen Sie Ihre Serverprotokolle
• 429 Too Many Requests: Sie werden ratenbegrenzt; implementieren Sie Backoff
• 5xx-Fehler: Serverseitige Probleme auf Ihrer Seite

Timeout-Probleme:

Zendesk hat ein strenges 10-Sekunden-Timeout. Wenn Ihr Endpunkt nicht innerhalb von 10 Sekunden antwortet, markiert Zendesk ihn als fehlgeschlagen und wiederholt den Vorgang. Stellen Sie sicher, dass Ihr Endpunkt schnell antwortet und schwere Arbeiten bei Bedarf asynchron verarbeitet.

Schutzschalter ausgelöst:

Wenn Ihr Webhook mit einer Fehlerrate von 70 % fehlschlägt oder in 5 Minuten mehr als 1.000 Fehler ansammelt, deaktiviert Zendesk ihn automatisch. Sie müssen das zugrunde liegende Problem beheben und den Webhook manuell wieder aktivieren.

Fehlende Aktivitätsprotokolle:

Zendesk speichert Webhook-Aktivitätsprotokolle nur 7 Tage lang. Wenn Sie eine längere Aufbewahrungsdauer benötigen, müssen Sie Webhook-Ereignisse auf Ihrer eigenen Infrastruktur protokollieren.

Alternative: Automatisieren ohne Webhooks

Webhooks sind leistungsstark, aber nicht immer das richtige Werkzeug. Sie erfordern technische Einrichtung, laufende Wartung und Fehlerbehandlung. Wenn Sie Automatisierung ohne die Komplexität wünschen, gibt es Alternativen.

Wir haben eesel AI entwickelt, um die Support-Automatisierung zu übernehmen, ohne dass Webhooks oder benutzerdefinierte Entwicklung erforderlich sind. Anstatt Endpunkte zu konfigurieren und JSON-Payloads zu analysieren, verbinden Sie eesel AI einfach mit Ihrem Zendesk-Konto. Es lernt aus Ihren vergangenen Tickets und Helpcenter-Artikeln und erledigt dann Routineaufgaben automatisch.

Hier ist der Unterschied:

Mit eesel AI können Sie:

• Tickets basierend auf dem Inhalt automatisch taggen und weiterleiten
• Entwürfe für Ihre Agenten erstellen
• Häufige Fragen End-to-End beantworten
• Komplexe Probleme an Menschen eskalieren

Das Beste daran? Sie können es an vergangenen Tickets testen, bevor Sie live gehen. Kein Risiko, Produktionsworkflows zu unterbrechen, während Sie die Einrichtung optimieren.

Beginnen Sie noch heute mit der Automatisierung Ihrer Zendesk-Workflows

Das Einrichten eines Zendesk-Webhooks für Ticket-Erstellungsereignisse gibt Ihnen Echtzeit-Einblick in neue Supportanfragen. Ob Sie Slack-Kanäle benachrichtigen, mit einem CRM synchronisieren oder benutzerdefinierte Workflows auslösen, Webhooks bieten die Verbindung zwischen Zendesk und dem Rest Ihres Stacks.

Der Prozess ist einfach: Erstellen Sie den Webhook, wählen Sie Ihre Verbindungsmethode, konfigurieren Sie einen Trigger (falls erforderlich) und testen Sie gründlich. Achten Sie auf Authentifizierung und Fehlerbehandlung, um einen zuverlässigen Betrieb zu gewährleisten.

Wenn sich Webhooks für Ihre Bedürfnisse als übertrieben anfühlen, überlegen Sie, ob ein KI-gestützter Ansatz besser geeignet ist. Tools wie eesel AI können die Ticketbearbeitung ohne Webhook-Konfiguration oder Endpunktverwaltung automatisieren. Sie können eesel AI kostenlos testen und sehen, wie es Ihre spezifischen Tickettypen verarbeitet, bevor Sie sich für eine Webhook-basierte Lösung entscheiden.

In jedem Fall ist das Ziel dasselbe: Verbringen Sie weniger Zeit mit der manuellen Ticketverwaltung und mehr Zeit damit, Kunden tatsächlich zu helfen.