Zendesk Messaging Konversation erstellt Webhook: Eine vollständige Implementierungsanleitung

Echtzeit-Benachrichtigungen sind das Rückgrat moderner Support-Workflows. Wenn ein Kunde eine Konversation beginnt, müssen Ihre Systeme dies sofort wissen, nicht erst, wenn jemand manuell nach Updates sucht. Webhooks füllen diese Lücke.

Aber hier ist die Sache bei Zendesk: Sie haben zwei völlig unterschiedliche Webhook-Systeme, und der "Konversation erstellt"-Webhook funktioniert anders, als die meisten Leute erwarten. Dieser Leitfaden beseitigt die Verwirrung und zeigt Ihnen genau, wie Sie Konversations-Webhooks in Zendesk einrichten und verwenden, egal ob Sie KI-Integrationen erstellen, Daten mit Ihrem CRM synchronisieren oder Benachrichtigungen an Slack weiterleiten.

Was ist der Zendesk Messaging Konversation erstellt Webhook?

Lassen Sie uns zuerst ein häufiges Missverständnis ausräumen. Wenn Leute nach "Zendesk Messaging Konversation erstellt Webhook" suchen, denken sie normalerweise an die Sunshine Conversations Messaging-Plattform (die Infrastruktur, die Zendesk Messaging antreibt). Aber das eigentliche "Konversation erstellt"-Ereignis befindet sich in einem ganz anderen System.

Zendesk hat zwei Webhook-Architekturen:

Standard-Zendesk-Webhooks verarbeiten Tickets, Benutzer, Organisationen und ja, Konversationsereignisse. Diese befinden sich im Admin Center unter Apps und Integrationen.

Messaging-Webhooks (Sunshine Conversations) verarbeiten Echtzeit-Chatnachrichten über die Messaging-Plattform. Diese werden separat konfiguriert und verwenden andere Ereignistypen.

Das conversation.created-Ereignis, das Sie suchen? Es ist Teil des Standard-Webhook-Systems, nicht der Messaging-Plattform. Dies verwirrt viele Entwickler, die erwarten, es in der Messaging-Dokumentation zu finden.

Was macht dieser Webhook eigentlich? Wenn eine neue Konversation in Ihrem Zendesk-Konto beginnt, sei es über das Web Widget, das mobile SDK, WhatsApp oder einen anderen Kanal, wird dieser Webhook ausgelöst und sendet einen Payload mit allen Konversationsdetails an Ihren Endpunkt. Ihre Anwendung kann dann in Echtzeit reagieren: einen KI-Agenten auslösen, in Ihr Data Warehouse protokollieren, eine Benachrichtigung senden oder die Konversation basierend auf dem Quellkanal weiterleiten.

Voraussetzungen für die Einrichtung von Messaging-Webhooks

Bevor Sie mit der Konfiguration von Webhooks beginnen, stellen Sie sicher, dass Sie Folgendes haben:

• Admin-Zugriff auf das Zendesk Admin Center - Sie benötigen Berechtigungen, um Webhooks zu erstellen und Integrationen zu verwalten
• Eine Endpunkt-URL, die bereit ist, Payloads zu empfangen - Dies sollte eine öffentlich zugängliche HTTPS-URL sein, die POST-Anfragen akzeptieren kann
• Grundlegendes Verständnis der Webhook-Sicherheit - Sie sollten Signaturen überprüfen, um sicherzustellen, dass Anfragen tatsächlich von Zendesk stammen
• Einen Plan für den Umgang mit Wiederholungsversuchen und Fehlern - Ihr Endpunkt muss innerhalb von 12 Sekunden antworten, sonst wiederholt Zendesk den Vorgang

Eine wichtige Einschränkung, die Sie kennen sollten: Testkonten sind auf 10 Webhooks und 60 Aufrufe pro Minute begrenzt. Wenn Sie auf einem Testkonto testen, planen Sie entsprechend.

So erstellen Sie einen Konversations-Webhook in Zendesk

Es gibt zwei Möglichkeiten, Ihren Webhook einzurichten: über die Admin Center-UI oder über die API. Die UI ist schneller für einmalige Setups, während die API besser funktioniert, wenn Sie Bereitstellungen automatisieren oder mehrere Umgebungen verwalten.

Verwenden des Admin Centers

Schritt 1: Zugriff auf den Webhooks-Bereich

Navigieren Sie zum Admin Center und klicken Sie dann in der Seitenleiste auf Apps und Integrationen. Wählen Sie im Untermenü Webhooks > Webhooks.

Schritt 2: Erstellen Sie den Webhook

Klicken Sie auf Webhook erstellen und wählen Sie Ihre Verbindungsmethode. Wählen Sie für Konversationsereignisse Zendesk-Ereignisse (nicht Auslöser oder Automatisierung).

Die Wahl der Verbindungsmethode ist dauerhaft. Sobald Sie einen Webhook als "Zendesk-Ereignisse" erstellen, können Sie ihn später nicht mehr in einen auslöserbasierten Webhook konvertieren. Wenn Sie beide Ereignistypen benötigen, erstellen Sie separate Webhooks.

Schritt 3: Konfigurieren Sie die Webhook-Einstellungen

Füllen Sie die grundlegende Konfiguration aus:

• Name und Beschreibung - Verwenden Sie etwas Beschreibendes wie "Neue Konversationsbenachrichtigungen", damit Ihr Team weiß, was es tut
• Endpunkt-URL - Ihr HTTPS-Endpunkt, der die Payloads empfängt
• Anfragemethode - POST (dies ist für ereignisabonnierte Webhooks festgelegt)
• Anfrageformat - JSON (auch für Ereignisabonnements festgelegt)

Schritt 4: Wählen Sie das Konversation erstellt Ereignis aus

Wählen Sie im Abschnitt Ereignisabonnements zen:event-type:conversation.created aus dem Dropdown-Menü. Sie können bei Bedarf mehrere Ereignisse abonnieren (z. B. conversation.updated oder conversation.closed).

Schritt 5: Richten Sie die Authentifizierung ein

Wählen Sie Ihre Authentifizierungsmethode:

Für die Produktion sollten Sie auch die Signaturüberprüfung aktivieren. Zendesk signiert jede Anfrage mit HMAC SHA256, und Sie können die Signatur anhand des Signierungsgeheimnisses Ihres Webhooks überprüfen, um sicherzustellen, dass die Anfragen legitim sind.

Verwenden der API

Verwenden Sie für die programmgesteuerte Einrichtung die Webhooks-API:

curl -X POST https://{subdomain}.zendesk.com/api/v2/webhooks \
  -u {email_address}/token:{api_token} \
  -H "Content-Type:application/json" \
  -d '{
    "webhook": {
      "name": "Conversation Created Webhook",
      "status": "active",
      "endpoint": "https://your-endpoint.com/webhook",
      "http_method": "POST",
      "request_format": "json",
      "subscriptions": [
        "zen:event-type:conversation.created"
      ],
      "authentication": {
        "type": "bearer_token",
        "data": {
          "token": "YOUR_TOKEN"
        },
        "add_position": "header"
      }
    }
  }'

Die API gibt eine eindeutige Webhook-ID zurück, die Sie für die Überwachung und Aktualisierung verwenden.

Verstehen des Konversation erstellt Webhook-Payloads

Wenn eine Konversation erstellt wird, sendet Zendesk einen JSON-Payload an Ihren Endpunkt. Hier ist, was Sie erwarten können:

{
  "account_id": 21825834,
  "detail": {
    "id": "141"
  },
  "event": {
    "conversation_id": "67ab5f53a96f98663935c3f2",
    "created_at": "2025-02-11T14:32:05Z",
    "source_channel": "web",
    "participant_count": 1
  },
  "id": "01JQMQH83YNAKWSWJ8B1QH2NSC",
  "subject": "zen:ticket:141",
  "time": "2025-02-11T14:32:05.254571515Z",
  "type": "zen:event-type:conversation.created",
  "zendesk_event_version": "2022-11-06"
}

Wichtige Felder, auf die Sie achten sollten:

• detail.id - Die Ticket-ID, die dieser Konversation zugeordnet ist
• event.conversation_id - Der eindeutige Konversationsbezeichner
• event.source_channel - Wo die Konversation ihren Ursprung hat (Web, WhatsApp, Facebook usw.)
• type - Der Ereignistyp, der diesen Webhook ausgelöst hat

Die Payload-Struktur unterscheidet sich von Messaging-Webhooks (die ein verschachteltes events-Array mit conversation:message-Typen verwenden). Standard-Konversations-Webhooks haben eine flachere Struktur, die sich auf den Konversationslebenszyklus und nicht auf einzelne Nachrichten konzentriert.

Authentifizierung und Sicherheitsrichtlinien

Webhooks sind nur so sicher wie Ihr Überprüfungsprozess. Da Ihr Endpunkt öffentlich zugänglich ist, müssen Sie überprüfen, ob Anfragen tatsächlich von Zendesk stammen.

Signaturüberprüfung

Jede Webhook-Anfrage enthält zwei Header:

• X-Zendesk-Webhook-Signature - Die HMAC SHA256-Signatur
• X-Zendesk-Webhook-Signature-Timestamp - Unix-Zeitstempel, wann die Anfrage gesendet wurde

So überprüfen Sie eine Anfrage:

1. Extrahieren Sie beide Header aus der eingehenden Anfrage
2. Verketten Sie den Zeitstempel und den Anfragetext (Zeitstempel + "." + Text)
3. Generieren Sie einen HMAC SHA256-Hash mit dem Signierungsgeheimnis Ihres Webhooks
4. Base64-codieren Sie das Ergebnis
5. Vergleichen Sie es mit dem Signatur-Header

Der Algorithmus lautet: base64(HMACSHA256(TIMESTAMP + "." + BODY))

Sie finden Ihr Signierungsgeheimnis im Admin Center, indem Sie auf der Einstellungsseite Ihres Webhooks auf "Geheimnis anzeigen" klicken. Verwenden Sie für Tests vor der Erstellung des Webhooks dieses statische Testgeheimnis: dGhpc19zZWNyZXRfaXNfZm9yX3Rlc3Rpbmdfb25seQ==

HTTPS-Anforderung

Verwenden Sie für Produktions-Webhooks immer HTTPS-Endpunkte. Neben den Sicherheitsvorteilen funktionieren einige Funktionen wie benutzerdefinierte Header und bestimmte Authentifizierungsmethoden nur mit HTTPS.

Idempotenz

Zendesk unternimmt alle Anstrengungen, um Webhooks genau einmal zuzustellen, kann dies aber nicht garantieren. Ihr Endpunkt kann dasselbe Konversation erstellt Ereignis mehrmals empfangen, insbesondere bei Wiederholungsversuchen oder wenn der Circuit Breaker aktiviert wird.

Entwerfen Sie Ihren Handler so, dass er idempotent ist: Überprüfen Sie, ob Sie eine Konversations-ID bereits verarbeitet haben, bevor Sie Maßnahmen ergreifen. Dies verhindert doppelte Benachrichtigungen, doppelte CRM-Einträge oder das zweimalige Auslösen derselben Automatisierung.

Behandeln von Webhook-Ereignissen in Ihrer Anwendung

Hier ist ein grundlegendes Muster für die Behandlung von Konversations-Webhooks in Node.js:

const crypto = require('crypto');

app.post('/webhook', (req, res) => {
  // Verify signature
  const signature = req.headers['x-zendesk-webhook-signature'];
  const timestamp = req.headers['x-zendesk-webhook-signature-timestamp'];
  const payload = JSON.stringify(req.body);

  const expectedSignature = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(`${timestamp}.${payload}`)
    .digest('base64');

  if (signature !== expectedSignature) {
    return res.status(401).send('Invalid signature');
  }

  // Process the event asynchronously
  const event = req.body;

  if (event.type === 'zen:event-type:conversation.created') {
    // Queue for processing - don't block the response
    processConversationCreated(event);
  }

  // Respond quickly to prevent retries
  res.status(200).send('OK');
});

Die wichtigsten Prinzipien:

• Überprüfen Sie die Signatur vor der Verarbeitung
• Antworten Sie schnell mit 200 OK (innerhalb von 12 Sekunden)
• Verarbeiten Sie das Ereignis asynchron - lassen Sie Ihre Geschäftslogik die HTTP-Antwort nicht blockieren
• Behandeln Sie doppelte Ereignisse ordnungsgemäß

Häufige Integrationsmuster

KI-Agenten-Auslösung - Wenn eine Konversation erstellt wird, überprüfen Sie, ob ein KI-Agent sie zuerst bearbeiten soll, bevor Sie sie an menschliche Agenten weiterleiten. Überprüfen Sie den Quellkanal, die Tageszeit oder das Kundensegment, um die Routing-Entscheidung zu treffen.

CRM-Protokollierung - Protokollieren Sie den Konversationsstart in Ihrem CRM für Berichte und Analysen. Fügen Sie die Kanalquelle hinzu, um zu verstehen, woher Kunden sich melden.

Slack-Benachrichtigungen - Senden Sie eine Benachrichtigung an einen Slack-Kanal, wenn Konversationen mit hoher Priorität beginnen, oder leiten Sie verschiedene Kanäle basierend auf der Quelle an verschiedene Slack-Kanäle weiter.

Wenn Sie KI-Integrationen erstellen und die Webhook-Entwicklung vollständig überspringen möchten, verbindet sich eesel AI direkt mit Zendesk und verarbeitet die Konversationsverarbeitung, ohne dass benutzerdefinierte Webhook-Handler erforderlich sind. Wir hören auf Konversationsereignisse und generieren automatisch kontextbezogene Antworten basierend auf Ihrer Wissensdatenbank.

Fehlerbehebung bei häufigen Webhook-Problemen

Auch richtig konfigurierte Webhooks können fehlschlagen. So diagnostizieren und beheben Sie die häufigsten Probleme:

Verbindungsfehler

Circuit-Breaker-Aktivierung

Wenn Ihr Endpunkt anfängt, Fehler zurückzugeben, wird der Circuit Breaker von Zendesk aktiviert, um Ihren Server vor Überlastung zu schützen. Er wird ausgelöst, wenn ein erheblicher Prozentsatz der Anfragen innerhalb eines kurzen Zeitfensters fehlschlägt.

Wenn aktiviert, werden Webhooks kurzzeitig pausiert. Nach der Pause versucht Zendesk es erneut. Wenn diese Anfrage fehlschlägt, löst der Circuit Breaker eine weitere Pause aus. Dieser Zyklus wird fortgesetzt, bis eine Anfrage erfolgreich ist.

Hinweis: Der Circuit Breaker wird typischerweise nicht bei Webhooks mit geringem Volumen aktiviert, sodass kleine Testumgebungen im Allgemeinen vor versehentlichen Sperren geschützt sind.

Debugging-Tipps

• Überprüfen Sie die Webhook-Aktivitätsprotokolle im Admin Center (werden 7 Tage lang aufbewahrt)
• Filtern Sie nach Status, um fehlgeschlagene Aufrufe anzuzeigen: Fügen Sie ?filter[status]=failed zur API-Anfrage hinzu
• Verwenden Sie Tools wie ngrok oder Hookdeck, um während der Entwicklung tatsächliche Payloads zu überprüfen
• Überprüfen Sie, ob Ihr Payload-Format mit dem übereinstimmt, was Ihr Endpunkt erwartet - die Struktur unterscheidet sich zwischen Standard-Webhooks und Messaging-Webhooks

Referenz zum Wiederholungsverhalten

Optimieren Sie Webhook-Integrationen mit eesel AI

Das Erstellen benutzerdefinierter Webhook-Handler erfordert erhebliche Entwicklungszeit. Sie müssen die Signaturüberprüfung, die Wiederholungslogik, die Idempotenz und die Fehlerbehandlung verarbeiten, bevor Sie überhaupt zu Ihrer eigentlichen Geschäftslogik gelangen. Dann gibt es die laufende Wartung: Überwachung, Protokollierung und Aktualisierung, wenn sich die APIs von Zendesk weiterentwickeln.

Wenn Ihr Ziel die KI-gestützte Support-Automatisierung und nicht die Webhook-Infrastruktur ist, gibt es einen einfacheren Weg.

eesel AI verbindet sich direkt mit Ihrem Zendesk-Konto und übernimmt die gesamte Webhook-Komplexität für Sie:

• Echtzeit-Konversationsverarbeitung - Wir erfassen Ticket- und Messaging-Ereignisse, sobald sie auftreten, ohne dass eine Webhook-Entwicklung Ihrerseits erforderlich ist
• Kontextbezogene KI-Antworten - Unser System verwendet Ihre Wissensdatenbank, vergangene Tickets und Hilfeartikel, um Antworten zu generieren, die zu Ihrer Markenstimme passen
• Aktionen über Text hinaus - Suchen Sie nach Bestellungen in Shopify, bearbeiten Sie Rückerstattungen, aktualisieren Sie Ticketfelder und mehr, alles konfiguriert durch Anweisungen in natürlicher Sprache und nicht durch Code
• Schrittweise Einführung - Beginnen Sie mit dem Copilot-Modus, in dem Agenten KI-Entwürfe überprüfen, und gehen Sie dann zu autonomen Antworten über, wenn Sie Vertrauen gewinnen

Die Einrichtung dauert Minuten, nicht Tage. Verbinden Sie Ihr Zendesk-Konto, trainieren Sie mit Ihren vorhandenen Daten und wählen Sie Ihren Modus. Sie können Simulationen auf vergangenen Tickets durchführen, um die Qualität zu überprüfen, bevor Sie live gehen.

Ausgereifte Bereitstellungen mit eesel AI erreichen eine bis zu 81 % autonome Lösung mit typischen Amortisationszeiten von unter 2 Monaten. Wenn Sie erwägen, benutzerdefinierte Webhook-Handler für die KI-Integration zu erstellen, testen Sie eesel AI 7 Tage lang kostenlos und prüfen Sie, ob es Ihren Anwendungsfall abdeckt.

Beginnen Sie noch heute mit der Erstellung von Zendesk-Konversations-Webhooks

Der Konversation erstellt Webhook ist ein leistungsstarkes Tool für die Echtzeit-Support-Automatisierung. Egal, ob Sie KI-Agenten auslösen, Daten mit externen Systemen synchronisieren oder Benachrichtigungen weiterleiten, das Verständnis, wie Sie diese Webhooks richtig konfigurieren und verarbeiten, ist unerlässlich.

Denken Sie an die wichtigste Unterscheidung: Standard-Webhooks verarbeiten Konversationslebenszyklusereignisse (erstellt, aktualisiert, geschlossen), während Messaging-Webhooks den Echtzeit-Nachrichtenfluss verarbeiten. Das conversation.created-Ereignis befindet sich im Standard-Webhook-System und ist Ihr Einstiegspunkt, um auf neue Kundenkonversationen über alle Kanäle hinweg zu reagieren.

Beginnen Sie mit der Admin Center-UI, um sich mit der Payload-Struktur vertraut zu machen, und wechseln Sie dann zur API, wenn Sie bereit sind, zu automatisieren. Aktivieren Sie die Signaturüberprüfung vom ersten Tag an, entwerfen Sie für Idempotenz und antworten Sie schnell, um Wiederholungsstürme zu verhindern.

Für Teams, die KI-gestützten Support ohne den Infrastrukturaufwand erstellen, macht eesel AI benutzerdefinierte Webhook-Handler überflüssig und liefert gleichzeitig kontextbezogene, wissensbasierte Antworten. So oder so ist die Echtzeit-Konversationserkennung jetzt in Reichweite.