Zendesk Webhook Payload Format: Eine vollständige Entwickleranleitung

Webhooks verwandeln Ihr Zendesk-Konto in eine Echtzeit-Benachrichtigungs-Engine. Anstatt APIs nach Aktualisierungen abzufragen (Polling), pushen Webhooks Daten in Ihre Systeme, sobald etwas passiert: ein Ticket wird erstellt, ein Agent aktualisiert eine Priorität oder ein Kunde sendet Feedback. Um jedoch zuverlässige Integrationen zu erstellen, müssen Sie genau verstehen, welche Daten Zendesk sendet und wie diese strukturiert sind.

Dieser Leitfaden schlüsselt das Zendesk Webhook Payload Format von Grund auf auf. Sie erfahren mehr über die beiden Arten von Webhooks, die Zendesk anbietet, die genaue Struktur von Ereignis-Payloads, wie Sie die Webhook-Authentizität überprüfen und erhalten praktische Implementierungstipps. Egal, ob Sie eine benutzerdefinierte Integration erstellen oder Zendesk mit Tools von Drittanbietern verbinden, das Verständnis dieser Payload-Formate ist unerlässlich.

Bei eesel AI verarbeiten wir Webhook-Daten von Zendesk und anderen Plattformen, um intelligente Automatisierung zu ermöglichen. Das richtige Payload Format ist der erste Schritt zum Aufbau robuster, sicherer Integrationen.

Die zwei Arten von Zendesk Webhooks

Zendesk bietet zwei grundlegend verschiedene Webhook-Verbindungsmethoden an, und die Wahl, die Sie treffen, bestimmt Ihre Payload-Formatoptionen. Sie können diese Entscheidung später nicht mehr ändern, daher lohnt es sich, beide Ansätze im Voraus zu verstehen.

Ereignis-abonnierte Webhooks

Diese Webhooks abonnieren direkt Zendesk Systemereignisse. Wenn ein Benutzer erstellt wird, sich ein Ticketstatus ändert oder eine Organisation aktualisiert wird, sendet Zendesk automatisch einen Webhook an Ihren Endpunkt.

Folgendes müssen Sie wissen:

• HTTP-Methode: Nur POST
• Request-Format: Nur JSON
• Payload-Struktur: Festes Schema, das von Zendesk definiert wird
• Am besten geeignet für: Echtzeitbenachrichtigungen über Benutzer-, Organisations-, Help Center- oder Messaging-Aktivitäten

Die Payload ist vorhersehbar. Zendesk steuert, welche Daten gesendet werden, was weniger Flexibilität, aber auch weniger Raum für Konfigurationsfehler bedeutet.

Trigger- und Automatisierungs-Webhooks

Diese verbinden sich mit den Geschäftsregeln von Zendesk: Triggern und Automatisierungen. Sie definieren genau, wann der Webhook basierend auf Ticketbedingungen ausgelöst wird.

Hauptmerkmale:

• HTTP-Methoden: GET, POST, PUT, PATCH, DELETE
• Request-Format: JSON, XML oder Formular-codiert
• Payload-Struktur: Vollständig anpassbar mit Liquid-Markup-Platzhaltern
• Am besten geeignet für: Ticket-basierte Workflows mit bedingter Logik

Dieser Ansatz gibt Ihnen die vollständige Kontrolle über die Payload. Sie entscheiden, welche Daten Sie einbeziehen und wie Sie sie formatieren möchten.

Die richtige Vorgehensweise wählen

Wenn Sie auf Ticketänderungen mit benutzerdefinierter Logik reagieren müssen, verwenden Sie Trigger-Webhooks. Für breitere Systemereignisse wie Benutzererstellung oder Messaging-Aktivitäten sind ereignis-abonnierte Webhooks besser geeignet.

Anatomie einer Webhook-Anfrage

Jede Webhook-Anfrage von Zendesk enthält Standard-HTTP-Header, die Metadaten über die Anfrage bereitstellen. Das Verständnis dieser Header ist entscheidend für Routing, Protokollierung und Sicherheitsüberprüfung.

Standard-Header

Die Signatur-Header sind optional, werden aber für Produktionsintegrationen empfohlen. Sie ermöglichen es Ihnen zu überprüfen, ob Anfragen tatsächlich von Zendesk stammen, und helfen, Replay-Angriffe zu verhindern.

Unterschiede in der Request-Struktur

Ereignis-abonnierte Webhooks verwenden immer POST mit JSON-Payloads. Der Body enthält die vollständigen Ereignisdaten in einem standardisierten Schema.

Trigger-Webhooks variieren je nach Ihrer Konfiguration. Eine GET-Anfrage kann Parameter in der URL enthalten, während POST-Anfragen einen Body enthalten, der je nach Ihren Einstellungen als JSON, XML oder Formular-codierte Daten formatiert ist.

Ereignis-Payload-Struktur und Beispiele

Ereignis-abonnierte Webhooks verwenden ein konsistentes JSON-Schema für alle Ereignistypen. Sobald Sie die Struktur verstanden haben, wird das Parsen jedes Ereignisses unkompliziert.

Standard-Ereignis-Schema

Jede Ereignis-Payload enthält diese Eigenschaften der obersten Ebene:

{
  "type": "zen:event-type:ticket.created",
  "account_id": 12514403,
  "id": "2b24ef10-19d4-4740-93cf-8f98ec4776c0",
  "time": "2099-07-04T05:33:18Z",
  "zendesk_event_version": "2022-06-20",
  "subject": "zen:ticket:12345",
  "detail": { /* resource details */ },
  "event": { /* change information */ }
}

Ticket-Erstellungsereignis

Wenn ein neues Ticket erstellt wird, sendet Zendesk eine Payload wie diese:

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

Das detail-Objekt enthält den vollständigen Ticket-Datensatz. Das event-Objekt für Erstellungsereignisse enthält nur Metadaten über die Ereignissequenz.

Statusänderungsereignis

Update-Ereignisse enthalten ein detaillierteres event-Objekt, das zeigt, was sich geändert hat:

{
  "event": {
    "current": "OPEN",
    "meta": {
      "sequence": {
        "id": 39313930383633353634323835,
        "position": 1
      }
    },
    "previous": "NEW"
  }
}

Die Eigenschaften current und previous zeigen die Vorher- und Nachher-Werte. Für Statusänderungen sind mögliche Werte: NEW, OPEN, PENDING, HOLD, SOLVED, CLOSED, DELETED, ARCHIVED und SCRUBBED.

Prioritätsänderungsereignis

Prioritätsereignisse folgen dem gleichen Muster:

{
  "event": {
    "current": "URGENT",
    "meta": { "sequence": { "id": 39313930383633353634323835, "position": 1 } },
    "previous": "NORMAL"
  }
}

Prioritätswerte sind: LOW, NORMAL, HIGH und URGENT.

Kommentar-hinzugefügt-Ereignis

Wenn jemand einen Kommentar zu einem Ticket hinzufügt:

{
  "event": {
    "comment": {
      "author": {
        "id": "8659716080510",
        "is_staff": false,
        "name": "John Smith"
      },
      "body": "Thanks for the quick response!",
      "id": "8659716087550",
      "is_public": true
    },
    "meta": { "sequence": { "id": 39313930383633353634323835, "position": 1 } }
  }
}

Das Kommentarobjekt enthält den vollständigen Text, Autoreninformationen und den Sichtbarkeitsstatus.

Tags-geändert-Ereignis

Für Tag-Aktualisierungen zeigt Zendesk, was hinzugefügt und entfernt wurde:

{
  "event": {
    "meta": { "sequence": { "id": 39313930383633353634323835, "position": 1 } },
    "tags_added": ["urgent", "vip"],
    "tags_removed": ["pending-review"]
  }
}

Diese Struktur erleichtert das Verfolgen von Tag-Änderungen, ohne vollständige Arrays zu vergleichen.

Trigger-Webhook-Payloads und Platzhalter

Trigger- und Automatisierungs-Webhooks geben Ihnen die vollständige Kontrolle über das Payload Format mithilfe von Liquid-Markup-Platzhaltern.

Häufige Platzhalter

Beispiel für eine benutzerdefinierte JSON-Payload

Sie können benutzerdefinierte Payloads wie diese erstellen:

{
  "event": "ticket_updated",
  "ticket_id": "{{ticket.id}}",
  "ticket_url": "{{ticket.url}}",
  "subject": "{{ticket.title}}",
  "description": "{{ticket.description}}",
  "status": "{{ticket.status}}",
  "priority": "{{ticket.priority}}",
  "requester": {
    "name": "{{ticket.requester.name}}",
    "email": "{{ticket.requester.email}}"
  },
  "assignee": {
    "name": "{{ticket.assignee.name}}",
    "email": "{{ticket.assignee.email}}"
  },
  "tags": "{{ticket.tags}}",
  "updated_by": "{{current_user.name}}"
}

Payload-Größenbeschränkungen

Benutzerdefinierte Payloads haben eine maximale Größe von 256 KB. Wenn Ihre Payload dieses Limit überschreitet, schneidet Zendesk sie ab. Sie sollten Payloads im Auge behalten, die große Beschreibungsfelder oder viele benutzerdefinierte Felder enthalten.

Authentifizierung und Sicherheit

Die Sicherung Ihrer Webhook-Endpunkte ist von entscheidender Bedeutung. Zendesk bietet mehrere Authentifizierungsoptionen, um eingehende Anfragen zu überprüfen.

Signaturüberprüfung

Die sicherste Methode verwendet HMAC-SHA256-Signaturen. Zendesk generiert eine Signatur aus dem Zeitstempel und dem Request-Body, die Sie auf Ihrem Server überprüfen können.

Algorithmus: base64(HMACSHA256(TIMESTAMP + BODY))

Node.js-Verifizierungsbeispiel:

const crypto = require("crypto");

const SIGNING_SECRET = "your_webhook_signing_secret";
const SIGNING_SECRET_ALGORITHM = "sha256";

function isValidSignature(signature, body, timestamp) {
  let hmac = crypto.createHmac(SIGNING_SECRET_ALGORITHM, SIGNING_SECRET);
  let sig = hmac.update(timestamp + body).digest("base64");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(sig)
  );
}

Python-Verifizierungsbeispiel:

import hmac
import hashlib
import base64

def verify_signature(payload, signature, timestamp, secret):
    message = timestamp + payload
    computed = base64.b64encode(
        hmac.new(
            secret.encode('utf-8'),
            message.encode('utf-8'),
            hashlib.sha256
        ).digest()
    ).decode('utf-8')
    return hmac.compare_digest(computed, signature)

Signierungsgeheimnisse

Jeder Webhook hat ein eindeutiges Signierungsgeheimnis. Sie können es im Zendesk Admin Center abrufen, indem Sie auf der Webhook-Detailseite auf "Geheimnis anzeigen" klicken, oder über die API unter GET /api/v2/webhooks/{id}/signing_secret.

Verwenden Sie für das Testen von Webhooks vor der Erstellung dieses statische Geheimnis: dGhpc19zZWNyZXRfaXNfZm9yX3Rlc3Rpbmdfb25seQ==

Zusätzliche Authentifizierungsmethoden

Neben der Signaturüberprüfung unterstützt Zendesk:

• API-Schlüsselauthentifizierung: Fügen Sie einen benutzerdefinierten Header mit Ihrem API-Schlüssel hinzu
• Basisauthentifizierung: Benutzername und Passwort oder API-Token
• Bearer-Token: OAuth-ähnliche Token-Authentifizierung

Sicherheits-Best Practices

• Verwenden Sie immer HTTPS-Endpunkte
• Überprüfen Sie Signaturen in Produktionsumgebungen
• Validieren Sie Zeitstempel, um Replay-Angriffe zu verhindern (lehnen Sie Anfragen ab, die älter als 5 Minuten sind)
• Speichern Sie Geheimnisse in Umgebungsvariablen, niemals im Code
• Machen Sie Ihre Webhook-Handler idempotent (Zendesk kann Wiederholungen versuchen oder Duplikate senden)

Testen und Fehlerbehebung

Bevor Sie Webhooks in der Produktion bereitstellen, benötigen Sie zuverlässige Teststrategien.

Verwendung von webhook.site

Webhook.site bietet eine kostenlose, temporäre URL, die eingehende Anfragen erfasst. Es ist perfekt, um Roh-Webhook-Payloads während der Entwicklung zu überprüfen. Sie erhalten eine eindeutige URL, die Header und Body-Inhalt in Echtzeit anzeigt.

Die integrierte Testfunktion von Zendesk

Beim Erstellen oder Bearbeiten eines Webhooks im Admin Center bietet Zendesk eine Testfunktion. Sie können eine Test-Payload an Ihren Endpunkt senden und die Antwort sehen. Dies hilft, Konnektivität und Payload Format zu überprüfen, bevor Sie live gehen.

Häufige Fehler und Lösungen

Wiederholungsverhalten

Zendesk wiederholt fehlgeschlagene Webhooks automatisch:

• HTTP 409-Fehler: bis zu 3 Wiederholungen
• HTTP 429/503 mit Retry-After-Header unter 60 Sekunden: wiederholt
• Timeouts (12-Sekunden-Limit): bis zu 5 Wiederholungen

Der Circuit Breaker wird aktiviert, wenn 70 % der Anfragen innerhalb von 5 Minuten fehlschlagen oder mehr als 1.000 Fehler auftreten. Er pausiert den Webhook für 5 Sekunden und versucht dann eine Anfrage. Wenn dies erfolgreich ist, wird der normale Betrieb wieder aufgenommen.

Integration von Webhooks mit eesel AI

Webhooks werden leistungsfähiger, wenn sie mit intelligenter Verarbeitung kombiniert werden. Bei eesel AI helfen wir Teams, Workflows zu automatisieren, indem wir Webhook-Daten von Zendesk und anderen Plattformen verarbeiten.

So verbessert die Webhook-Integration den Support-Betrieb:

• Intelligente Triage: Verarbeiten Sie Ticket-Erstellungs-Webhooks, um Tickets basierend auf Inhaltsanalyse automatisch zu kategorisieren und weiterzuleiten
• Automatisierte Antworten: Lösen Sie kontextbezogene Antworten mithilfe von Webhook-Daten über Ticketstatus- und Prioritätsänderungen aus
• Datenanreicherung: Kombinieren Sie Webhook-Payloads mit internen Datenquellen, um Agenten einen umfassenden Kundenkontext zu bieten
• Plattformübergreifende Synchronisierung: Verwenden Sie Webhooks, um Zendesk mit CRM-, Inventar- oder anderen Geschäftssystemen synchron zu halten

Unsere Zendesk-Integration verbindet sich direkt mit Ihrem Konto und lernt aus Ihren vergangenen Tickets und dem Help Center, um intelligente Automatisierung bereitzustellen. Webhooks erweitern diese Fähigkeit, indem sie Echtzeit-Trigger und -Aktionen ermöglichen.

Wichtige Erkenntnisse und Best Practices

Der Aufbau zuverlässiger Webhook-Integrationen erfordert Liebe zum Detail. Folgendes sollten Sie sich merken:

Wählen Sie den richtigen Webhook-Typ: Ereignis-abonnierte Webhooks funktionieren am besten für systemweite Benachrichtigungen, während Trigger-Webhooks Ihnen Flexibilität für ticketspezifische Workflows bieten.

Überprüfen Sie Signaturen in der Produktion: Die HMAC-SHA256-Signaturüberprüfung stellt sicher, dass Anfragen von Zendesk stammen und nicht manipuliert wurden.

Behandeln Sie Wiederholungen elegant: Zendesk kann fehlgeschlagene Anfragen wiederholen oder Duplikate senden. Entwerfen Sie Ihre Handler so, dass sie idempotent sind.

Überwachen Sie den Webhook-Zustand: Verwenden Sie das Aktivitätsprotokoll und den Circuit-Breaker-Status, um Probleme frühzeitig zu erkennen.

Testen Sie gründlich: Verwenden Sie Tools wie webhook.site, um Payloads zu überprüfen, bevor Sie sie in der Produktion bereitstellen.

Das Verständnis des Zendesk Webhook Payload Formats ist die Grundlage für den Aufbau robuster Integrationen. Mit dem richtigen Ansatz für Sicherheit, Tests und Fehlerbehandlung können Sie zuverlässige Verbindungen erstellen, die Ihre Systeme synchron halten und Ihr Team informieren.