Webhooks: technische Referenz

Endpoints und Abonnements#

• Endpoints werden pro Workspace unter Einstellungen > Webhooks verwaltet (Berechtigung erforderlich; standardmäßig Owner und Admins).
• Jeder Endpoint abonniert eine Auswahl von Event-Typen oder per Wildcard * alle aktuellen und künftigen Events.
• Pro Endpoint können eigene HTTP-Header hinterlegt werden (etwa ein API-Key deines Zielsystems). Die Signatur-Header der Plattform sind reserviert und nicht überschreibbar.
• Das Signing-Secret (whsec_ + Base64url) wird beim Anlegen genau einmal angezeigt und ist über Secret rotieren ersetzbar; das alte Secret wird dabei sofort ungültig.

Zustell-Envelope#

Jede Zustellung ist ein POST mit Content-Type: application/json:

Signatur prüfen (Standard-Webhooks)#

Drei Header begleiten jede Zustellung:

Die Signatur ist HMAC-SHA256 über die Zeichenkette {id}.{timestamp}.{body}. Der Schlüssel ist der Base64url-dekodierte Teil des Secrets nach dem Präfix whsec_.

import { createHmac, timingSafeEqual } from "node:crypto";
 
export function verifyWebhook(
  secret: string, // "whsec_..."
  id: string, // webhook-id header
  timestamp: string, // webhook-timestamp header
  signature: string, // webhook-signature header, "v1,<base64>"
  rawBody: string, // unveraenderter Request-Body als String
): boolean {
  const key = Buffer.from(secret.slice("whsec_".length), "base64url");
  const expected = createHmac("sha256", key)
    .update(`${id}.${timestamp}.${rawBody}`)
    .digest("base64");
  const given = signature.replace(/^v1,/, "");
  const a = Buffer.from(expected);
  const b = Buffer.from(given);
  return a.length === b.length && timingSafeEqual(a, b);
}

Fertige Standard-Webhooks-Bibliotheken existieren für alle gängigen Sprachen und übernehmen diese Schritte.

Zustellung, Wiederholungen, Auto-Pause#

• Erwartet wird eine Antwort mit Status 2xx innerhalb des Zustell-Timeouts. Alles andere gilt als Fehlversuch.
• Wiederholungs-Zeitplan nach Fehlversuchen: 1, 5, 30, 120, 720 Minuten (maximal 5 Versuche pro Zustellung).
• Nach 15 fehlgeschlagenen Zustellungen in Folge (ohne zwischenzeitlichen Erfolg) pausiert der Endpoint automatisch und muss nach Behebung manuell reaktiviert werden.
• Das Zustell-Log speichert pro Versuch Status, Dauer und die ersten 2.048 Zeichen des Antwort-Bodys. Einzelne Zustellungen lassen sich manuell erneut zustellen.
• Test-Events: generisch (webhook.test) oder pro Event-Typ mit dessen Beispiel-Payload.

Event-Katalog#

Wortgleiche Typen, wie sie im type-Feld ankommen. Die Verwaltung zeigt zu jedem Event Beschreibung und Beispiel-Payload.

Betriebs-Empfehlungen#

• Signatur immer prüfen und webhook-id als Idempotenz-Schlüssel verwenden.
• Schnell mit 2xx antworten und die eigentliche Verarbeitung asynchron erledigen (Queue), damit der Zustell-Timeout nicht reißt.
• Reihenfolge nicht voraussetzen: bei Wiederholungen können Events außer der Reihe ankommen; createdAt nutzen.
• Endpoint-Pausierung überwachen (Zustell-Log) und nach Behebung reaktivieren.