So richten Sie Zendesk Messaging Message Delivered Webhooks ein

Webhooks verwandeln Ihr Zendesk in eine Echtzeit-Benachrichtigungs-Engine. Anstatt nach Aktualisierungen zu suchen (Polling), senden Webhooks Daten an Ihre Systeme, sobald etwas passiert. Speziell für Messaging ermöglichen Ihnen Delivery Webhooks, zu verfolgen, ob Nachrichten Ihre Kunden tatsächlich erreichen. Nicht nur an WhatsApp oder Twilio übergeben. Tatsächlich zugestellt.

Dies ist wichtig, da "gesendet" und "zugestellt" zwei verschiedene Dinge sind. Eine Nachricht könnte Zendesk verlassen, auf Carrier-Ebene fehlschlagen, und Sie würden es ohne Delivery-Tracking nie erfahren. Oder sie könnte unzustellbar sein, weil das Telefon eines Kunden offline ist. Delivery Webhooks geben Ihnen Einblick in den gesamten Lebenszyklus der Nachricht.

In dieser Anleitung erfahren Sie, wie Sie Zendesk Message Delivery Webhooks von Grund auf einrichten. Wir werden die drei Delivery Eventtypen behandeln, Sie Schritt für Schritt durch die Konfiguration führen und funktionierenden Code bereitstellen, den Sie für Ihre eigene Implementierung anpassen können.

Was Sie benötigen

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

• Ein Zendesk-Konto mit Administratorzugriff (die Webhook-Konfiguration erfordert Administratorberechtigungen)
• Einen HTTPS-Endpunkt, um Webhook-Payloads zu empfangen (ein Entwicklungsserver funktioniert gut zum Testen)
• Grundlegende Vertrautheit mit JSON- und HTTP-Konzepten
• Optional: ein Tool wie Postman oder curl zum Testen

Wenn Sie dies für die Produktion erstellen, sollten Sie auch über Authentifizierung, Fehlerbehandlung und Idempotenz nachdenken. Wir werden all diese Punkte ansprechen.

Verstehen von Zendesk Message Delivery Events

Die Messaging-Plattform von Zendesk sendet drei Arten von Delivery Events. Jedes sagt Ihnen etwas anderes darüber, wo Ihre Nachricht steht.

Die drei Delivery Eventtypen

So funktioniert der Ablauf. Wenn Sie eine Nachricht senden, trifft sie zuerst auf die API des Kanals. Wenn diese API die Nachricht akzeptiert, erhalten Sie ein delivery:channel Event. Für einige Kanäle (wie WhatsApp oder SMS über Twilio) erhalten Sie möglicherweise später ein delivery:user Event, das bestätigt, dass die Nachricht das Gerät erreicht hat. Wenn auf dem Weg etwas fehlschlägt, erhalten Sie delivery:failure mit spezifischen Fehlerinformationen.

Das Flag isFinalEvent gibt an, ob weitere Events folgen. Wenn isFinalEvent: true, ist dies der letzte Webhook, den Sie für diese Nachricht erhalten. Wenn false, unterstützt der Kanal die Zustellungsbestätigung auf Benutzerebene, erwarten Sie also eine Nachverfolgung.

Die Kanalunterstützung variiert

Nicht alle Kanäle können die Zustellung an den Benutzer bestätigen. Einige bestätigen nur, dass sie die Nachricht von Zendesk erhalten haben. Hier ist die Aufschlüsselung:

Kanäle mit vollständiger Zustellungsbestätigung (Kanal + Benutzer):

• WhatsApp
• Twilio SMS
• MessageBird
• iOS SDK, Android SDK, Unity SDK, Web Widget

Kanäle nur mit Kanalzustellung:

• Facebook Messenger
• Instagram
• LINE
• Telegram
• Viber
• WeChat
• X (Twitter)
• Apple Messages for Business

Für Kanäle ohne Benutzerbestätigung hat das delivery:channel Event isFinalEvent: true. Das ist Ihr Signal, dass keine weiteren Aktualisierungen kommen.

Warum dies für Ihre Implementierung wichtig ist

Wenn Sie Analysen auf Basis dieser Webhooks erstellen, sollten Sie diese Variation berücksichtigen. Eine "zugestellte" Metrik bedeutet je nach Kanal unterschiedliche Dinge. Für WhatsApp ist es die Bestätigung auf Geräteebene. Für Facebook Messenger bedeutet es nur, dass die API von Facebook die Nachricht akzeptiert hat.

Schritt 1: Erstellen Sie einen Webhook im Zendesk Admin Center

Lassen Sie uns gemeinsam Ihren ersten Delivery Webhook erstellen.

Navigieren Sie zuerst zu Admin Center > Apps und Integrationen > Webhooks. Wenn Sie die Webhooks-Option nicht sehen, überprüfen Sie, ob Ihre Rolle die entsprechenden Berechtigungen hat. Erfahren Sie mehr in der Zendesk Webhooks Dokumentation.

Klicken Sie auf Webhook erstellen. Sie sehen ein Formular mit mehreren Feldern:

Name: Geben Sie ihm etwas Beschreibendes wie "Message Delivery Tracker" oder "Production Delivery Events".

Endpunkt-URL: Dies ist der Ort, an dem Zendesk die Webhook-Payloads POSTen wird. Für die Entwicklung können Sie ein Tool wie ngrok verwenden, um einen lokalen Server freizugeben. Für die Produktion sollte dies eine HTTPS-URL in Ihrer Infrastruktur sein.

HTTP-Methode: Wählen Sie POST. Delivery Events verwenden immer POST.

Anfrageformat: Wählen Sie JSON.

Noch nicht speichern. Wir werden Event-Abonnements und Authentifizierung in den nächsten Schritten konfigurieren.

Schritt 2: Abonnieren Sie Delivery Events

Suchen Sie im Webhook-Erstellungsformular den Abschnitt Event-Abonnements. Hier geben Sie an, welche Events Ihren Webhook auslösen sollen.

Für die Message Delivery-Verfolgung abonnieren Sie diese drei Events:

1. conversation:message:delivery:channel
2. conversation:message:delivery:user
3. conversation:message:delivery:failure

Sie können bei Bedarf zusätzliche Events abonnieren (wie conversation:message für alle Nachrichten), aber für die Delivery-Verfolgung sind diese drei das, was Sie wollen.

Event-Filteroptionen:

Wenn Ihre Integration Teil der Switchboard ist, können Sie steuern, ob Sie Events für Konversationen erhalten, die Sie nicht aktiv verwalten. Die Einstellung deliverStandbyEvents filtert dies. Die meisten Integrationen setzen dies auf false, um nur Events für aktive Konversationen zu erhalten.

Speichern Sie den Webhook. Zendesk weist ihm eine eindeutige ID zu (beginnend mit 01). Kopieren Sie diese ID. Sie benötigen sie zum Testen und zum Verbinden mit Triggern, wenn Sie diesen Weg gehen.

Schritt 3: Richten Sie die Webhook-Authentifizierung ein

Webhooks ohne Authentifizierung sind ein Sicherheitsrisiko. Jeder, der Ihre Endpunkt-URL entdeckt, könnte gefälschte Events senden. Zendesk unterstützt verschiedene Authentifizierungsmethoden.

Verfügbare Authentifizierungsoptionen

Für die meisten Implementierungen bietet die API-Schlüsselauthentifizierung das richtige Gleichgewicht zwischen Sicherheit und Einfachheit.

Konfigurieren in Zendesk

Erweitern Sie im Webhook-Formular den Abschnitt Authentifizierung. Wählen Sie Ihre bevorzugte Methode aus und geben Sie die Anmeldeinformationen ein:

• Für API-Schlüssel: Geben Sie den Headernamen (z. B. X-API-Key) und den Schlüsselwert an
• Für Bearer Token: Geben Sie das Token ein, das Zendesk einfügen soll
• Für Basic Auth: Geben Sie Benutzername und Passwort an

Überprüfen von Webhook-Signaturen

Zendesk kann Webhooks mit HMAC-SHA256 signieren. Auf diese Weise können Sie überprüfen, ob Payloads tatsächlich von Zendesk stammen und nicht von einem Angreifer. Weitere Informationen zur Implementierung finden Sie in der Zendesk Webhook Signierungsdokumentation.

Um dies zu aktivieren, müssen Sie:

1. Generieren Sie ein Signierungsgeheimnis (Zendesk stellt dies bereit, wenn Sie die Signierung aktivieren)
2. Überprüfen Sie den X-Zendesk-Webhook-Signature Header in Ihrem Endpunkt
3. Berechnen Sie den HMAC-SHA256 der Payload mit Ihrem Geheimnis
4. Vergleichen Sie ihn mit dem Signatur-Header

Hier ist ein einfaches Node.js-Beispiel:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('base64');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Schritt 4: Erstellen Sie Ihren Webhook-Endpunkt

Nun zum spaßigen Teil: Erstellen Sie den Endpunkt, der diese Webhooks empfängt.

Grundlegende Anforderungen

Ihr Endpunkt muss:

• HTTPS verwenden (Zendesk lehnt HTTP-URLs ab)
• Innerhalb von 10 Sekunden antworten
• Einen 2xx-Statuscode für die erfolgreiche Verarbeitung zurückgeben
• Doppelte Events ordnungsgemäß verarbeiten (Idempotenz)

Beispiel für einen Webhook-Empfänger (Node.js/Express)

Hier ist ein minimaler, aber produktionsreifer Endpunkt:

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhooks/zendesk-delivery', (req, res) => {
  // Empfang sofort bestätigen
  res.status(200).send('OK');

  // Events asynchron verarbeiten
  const events = req.body.events || [];

  for (const event of events) {
    handleDeliveryEvent(event);
  }
});

function handleDeliveryEvent(event) {
  const { type, payload } = event;

  switch (type) {
    case 'conversation:message:delivery:channel':
      console.log(`Message ${payload.message.id} delivered to ${payload.destination.type}`);
      break;

    case 'conversation:message:delivery:user':
      console.log(`Message ${payload.message.id} reached user`);
      break;

    case 'conversation:message:delivery:failure':
      console.error(`Message ${payload.message.id} failed:`, payload.error);
      break;
  }
}

app.listen(3000, () => {
  console.log('Webhook endpoint listening on port 3000');
});

Wichtige Dinge, die dieses Beispiel tut:

1. Antwortet sofort (200 OK) vor der Verarbeitung
2. Verarbeitet Events asynchron
3. Behandelt jeden Eventtyp separat
4. Extrahiert relevante IDs für Protokollierung/Debugging

Umgang mit Wiederholungsversuchen und Idempotenz

Zendesk wiederholt fehlgeschlagene Webhooks (4xx/5xx-Antworten, Timeouts) bis zu 3-5 Mal, abhängig vom Fehler. Dies bedeutet, dass Ihr Endpunkt dasselbe Event mehrmals empfangen kann.

Um dies zu beheben, implementieren Sie Idempotenz:

const processedEvents = new Set(); // Verwenden Sie Redis in der Produktion

function handleDeliveryEvent(event) {
  if (processedEvents.has(event.id)) {
    console.log(`Skipping duplicate event: ${event.id}`);
    return;
  }

  // Verarbeiten Sie das Event...

  processedEvents.add(event.id);
}

Verwenden Sie in der Produktion Redis oder eine Datenbank, um verarbeitete Event-IDs mit TTL (Time to Live) zu verfolgen, sodass das Deduplizierungsfenster mit dem Wiederholungsverhalten von Zendesk übereinstimmt.

Schritt 5: Verstehen der Delivery Webhook-Payload

Lassen Sie uns aufschlüsseln, was tatsächlich in diesen Webhooks ankommt.

Gemeinsame Payload-Struktur

Alle Delivery Events teilen diese Wrapper-Struktur:

{
  "app": {
    "id": "5fb29b20fee5422428712475"
  },
  "webhook": {
    "id": "5ff5e98b0d0c6d8925594923",
    "version": "v2"
  },
  "events": [
    {
      "id": "5ff7595eafcaab0a685ff889",
      "createdAt": "2021-01-07T18:56:30.666Z",
      "type": "conversation:message:delivery:channel",
      "payload": {
        "conversation": { "id": "2d4fd3d00715d1e64611e248" },
        "user": { "id": "71268330a47f5c4b541fce46" },
        "destination": {
          "type": "whatsapp",
          "integrationId": "5ff75853b1c3000a6ad4f7f5"
        },
        "message": { "id": "5ff7595eb1c3000a6ad4f7fb" },
        "isFinalEvent": false,
        "externalMessages": [
          { "id": "wamid.HBgNNTUxQTk4MDUz5Tg4MRU..." }
        ]
      }
    }
  ]
}

Erläuterung der Schlüsselfelder

Besonderheiten des Failure Events

Wenn die Zustellung fehlschlägt, enthält die Payload ein Fehlerobjekt:

{
  "error": {
    "code": "bad_request",
    "message": "Message failed to send because more than 24 hours have passed since the customer last replied.",
    "underlyingError": {
      "errors": [{
        "code": 131047,
        "title": "Re-engagement message",
        "message": "Re-engagement message"
      }]
    }
  }
}

Das Feld underlyingError enthält den Rohfehler von der API des Kanals. Dies ist von unschätzbarem Wert für das Debuggen. Die Fehlercodes von WhatsApp beispielsweise geben genau an, warum eine Nachricht abgelehnt wurde.

Schritt 6: Testen Sie Ihre Webhook-Implementierung

Bevor Sie live gehen, müssen Sie überprüfen, ob alles funktioniert.

Verwenden des Webhook-Testers von Zendesk

Klicken Sie auf der Webhook-Konfigurationsseite auf Webhook testen. Zendesk sendet eine Test-Payload an Ihren Endpunkt und zeigt Ihnen die Antwort. Dies ist nützlich, um Konnektivität und Authentifizierung zu überprüfen.

Die Test-Payload ist jedoch generisch. Es wird kein echtes Delivery Event sein. Für realistische Tests müssen Sie tatsächliche Nachrichtenflüsse auslösen.

Testen mit echten Nachrichten

1. Senden Sie eine Testnachricht über Zendesk Messaging
2. Überprüfen Sie Ihre Endpunktprotokolle auf eingehende Webhooks
3. Überprüfen Sie, ob die Payload-Struktur den Erwartungen entspricht
4. Bestätigen Sie, dass Ihre Event-Handling-Logik jeden Typ korrekt verarbeitet

Für Kanäle, die die Benutzerzustellung unterstützen (wie WhatsApp), können Sie den Zwei-Event-Fluss überprüfen. Der erste Webhook sollte isFinalEvent: false haben. Der zweite (Benutzerzustellung) sollte isFinalEvent: true haben.

Überprüfen der Webhook-Aktivitätsprotokolle

Zendesk speichert Webhook-Protokolle für 7 Tage. Navigieren Sie zu Admin Center > Apps und Integrationen > Webhooks, wählen Sie Ihren Webhook aus und zeigen Sie die Registerkarte Aktivität an. Dies zeigt die letzten Zustellungen, Antwortcodes und alle Fehler an.

Wenn Sie die erwarteten Webhooks nicht sehen, überprüfen Sie:

• Ist der Webhook aktiv (nicht pausiert)?
• Sind die Event-Abonnements korrekt?
• Antwortet Ihr Endpunkt mit 2xx-Statuscodes?

Fehlerbehebung bei häufigen Problemen

Auch bei sorgfältiger Einrichtung geht etwas schief. Hier sind die häufigsten Probleme und wie Sie sie beheben können.

Webhook wird nicht ausgelöst

Wenn Sie keine Webhooks empfangen, wenn Nachrichten gesendet werden:

• Stellen Sie sicher, dass der Webhook aktiv ist (nicht pausiert oder im Entwurfszustand)
• Überprüfen Sie, ob die richtigen Eventtypen abonniert sind
• Überprüfen Sie bei Trigger-verbundenen Webhooks, ob die Triggerbedingungen erfüllt werden
• Überprüfen Sie die Webhook-Aktivitätsprotokolle auf Fehlermuster

Authentifizierungsfehler (401/403)

Wenn Zendesk Authentifizierungsfehler meldet:

• Stellen Sie sicher, dass Ihr Endpunkt den richtigen Header überprüft
• Bestätigen Sie, dass der API-Schlüssel/das Token nicht abgelaufen ist
• Überprüfen Sie die Groß-/Kleinschreibung in Headernamen
• Wenn Sie die Signaturüberprüfung verwenden, stellen Sie sicher, dass Sie den HMAC korrekt berechnen

Timeouts und Circuit Breaker

Zendesk hat ein 10-Sekunden-Timeout. Wenn Ihr Endpunkt länger dauert:

• Antworten Sie sofort (200 OK) und verarbeiten Sie asynchron
• Verwenden Sie eine Message Queue (SQS, RabbitMQ usw.) für die intensive Verarbeitung
• Überwachen Sie die Verarbeitungszeiten und optimieren Sie langsame Vorgänge

Der Circuit Breaker löst bei einer Fehlerrate von 70 % oder mehr als 1.000 Fehlern in 5 Minuten aus. Wenn dies geschieht, pausiert Zendesk Ihren Webhook. Sie müssen das zugrunde liegende Problem beheben und den Webhook manuell reaktivieren.

Fehlende Delivery Events

Wenn Sie einige Events sehen, aber nicht andere:

• Überprüfen Sie die Kanalunterstützungsmatrix. Nicht alle Kanäle senden Benutzerzustellungsbestätigungen.
• Insbesondere bei WhatsApp können Benutzerzustellungs-Events verzögert oder unterdrückt werden, wenn die Nachricht außerhalb eines bestimmten Zeitfensters empfangen wird.
• Überprüfen Sie das isFinalEvent-Verhalten. Wenn es auf Kanalebene true ist, folgt kein Benutzerzustellungs-Event.

Best Practices für die Produktion

Sobald Ihr Webhook funktioniert, sollten Sie diese Produktions-Empfehlungen berücksichtigen.

Fehlerbehandlung und Überwachung

• Protokollieren Sie alle Webhook-Eingänge mit Event-IDs zum Debuggen
• Richten Sie Warnungen für erhöhte Fehlerraten ein
• Überwachen Sie die Antwortzeiten des Endpunkts
• Verfolgen Sie die Zustellungsraten nach Kanal, um Probleme frühzeitig zu erkennen

Sicherheit

• Verwenden Sie in der Produktion immer HTTPS
• Implementieren Sie die Webhook-Signaturüberprüfung
• Rotieren Sie API-Schlüssel regelmäßig
• Protokollieren Sie keine sensiblen Payload-Daten

Datenaufbewahrung

Delivery Events enthalten Nachrichten-Metadaten. Berücksichtigen Sie:

• Wie lange Eventprotokolle aufbewahrt werden sollen
• Ob vollständige Payloads oder nur Schlüsselfelder gespeichert werden sollen
• Compliance-Anforderungen (DSGVO usw.) für Nachrichtendaten

Wann soll Polling verwendet werden und wann Webhooks

Webhooks sind ideal für Echtzeit-Updates. Wenn Sie jedoch historische Daten benötigen oder Events verpasst haben, müssen Sie möglicherweise durch Polling ergänzen. Die List Messages API kann Lücken füllen.

Optimieren Sie Messaging-Workflows mit eesel AI

Das Erstellen benutzerdefinierter Webhook-Endpunkte erfordert Engineering-Zeit. Sie müssen Authentifizierung, Wiederholungsversuche, Idempotenz und Fehlerfälle behandeln. Dann müssen Sie die eigentliche Geschäftslogik auf Basis dieser Events erstellen.

Wir haben eesel AI entwickelt, um diese Komplexität für Sie zu bewältigen. Anstatt Webhooks selbst zu verwalten, erhalten Sie eine schlüsselfertige Messaging-Automatisierung mit integrierter Delivery-Verfolgung. Unser KI-Teamkollege integriert sich in Zendesk (und Freshdesk, Gorgias und andere), um Konversationen End-to-End zu verarbeiten.

Wenn Sie nach einem schnelleren Weg zu KI-gestütztem Messaging suchen, lesen Sie unseren vollständigen Leitfaden zu Zendesk Messaging Webhooks. Und wenn Sie Optionen vergleichen möchten, sehen Sie sich unsere Aufschlüsselung der besten KI-Chatbots für Zendesk an.