Webhooks

Webhooks senden eine HTTP-Anfrage an Ihren Endpunkt, wenn ein Trigger oder eine Automatisierung auslöst. Sie legen sie unter Admin Center, Integrations, Webhooks an und nutzen sie dann als Aktion in jedem Trigger und jeder Automatisierung. Request-Bodies können Platzhalter nutzen und folgen Payloads im Zendesk-Format, sodass Empfänger für Zendesk-Webhooks oft unverändert funktionieren.

Signatur prüfen

Jede Anfrage trägt zwei Header:

Header	Wert
X-Desk-Timestamp	Unix-Zeit in Sekunden, zu der die Anfrage signiert wurde
X-Desk-Signature	base64(HMAC-SHA256(signing secret, timestamp + "." + raw body))

Berechnen Sie die Signatur über den unveränderten Request-Body, vergleichen Sie in konstanter Zeit und lehnen Sie Anfragen ab, deren Zeitstempel älter als 5 Minuten ist.

import crypto from 'node:crypto';

export function verify(rawBody, headers, secret) {
  const ts = headers['x-desk-timestamp'];
  const sig = headers['x-desk-signature'];
  if (!ts || !sig || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('base64');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
}

function verify(string $rawBody, string $ts, string $sig, string $secret): bool
{
    if (abs(time() - (int) $ts) > 300) {
        return false;
    }
    $expected = base64_encode(hash_hmac('sha256', $ts.'.'.$rawBody, $secret, true));

    return hash_equals($expected, $sig);
}

import base64, hashlib, hmac, time

def verify(raw_body: bytes, ts: str, sig: str, secret: str) -> bool:
    if not ts or not sig or abs(time.time() - int(ts)) > 300:
        return False
    mac = hmac.new(secret.encode(), ts.encode() + b"." + raw_body, hashlib.sha256)
    expected = base64.b64encode(mac.digest()).decode()
    return hmac.compare_digest(expected, sig)

Wiederholungen

Antworten Sie innerhalb weniger Sekunden mit einem beliebigen 2xx-Status. Andere Antworten und Timeouts werden nach 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden, 6 Stunden und 12 Stunden wiederholt; danach gilt die Zustellung als fehlgeschlagen. Jeder Versuch steht mit Status und Antwort im Zustellprotokoll des Webhooks.

Machen Sie Ihren Empfänger idempotent: Eine Zustellung kann mehr als einmal ankommen.

Zustellprotokoll und manuelle Wiederholung

Admin Center, Integrations, Webhooks zeigt jede Zustellung mit Anfrage, Antwort, Status und Versuchen. Filtern Sie nach Webhook, Ereignis (ticket.created, trigger, automation, test und so weiter) und Status. Replay bei einer Zustellung, auch einer endgültig fehlgeschlagenen, stellt eine frische Kopie derselben Payload in die Warteschlange, signiert mit dem aktuellen Secret; die Kopie ist mit dem Original verknüpft. Dasselbe Protokoll gibt es in der API: GET /api/webhook_deliveries?event_type=ticket.created&status=failed und POST /api/webhook_deliveries/{id}/replay.

Payload-Version

Jede Zustellung und jeder Ping trägt im Umschlag eine Ganzzahl version, heute 1. Sie ist Teil des öffentlichen Vertrags: Ein inkompatibler Umschlag bekommt eine neue Zahl, pro Webhook festgelegt, und beide Versionen werden zugestellt, solange eine alte ausläuft. Lesen Sie version in Ihrem Empfänger, statt aus der Form des Bodys zu raten, und ignorieren Sie Felder, die Sie nicht kennen. Die Regeln, einschließlich 12 Monaten Vorlauf, bevor etwas entfernt wird, stehen unter Versionierung und Abkündigung.

Ausgehende Adressen

Webhook-Anfragen kommen von unseren veröffentlichten ausgehenden IP-Adressen, sodass Sie sie in Ihrer Firewall freigeben können.