API: Webhooks

Ein Webhook ist eine URL, an die Eventwerk bei einer neuen Benachrichtigung einen HTTP-POST sendet. Webhooks gehören zu Eventwerk Plus. Sie werden pro Organisation verwaltet.

Webhooks verwalten

Ein Webhook enthält id, url, secret, created_at und revoked_at. Die Liste zeigt nur nicht widerrufene Webhooks. Das Geheimnis steht in der Antwort und dient der Signaturprüfung.

curl -s -X POST /api/webhooks \
  -H "Authorization: Bearer <Access-Token>" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.test/eventwerk-hook"}'

• Die URL muss mit http oder https beginnen und höchstens 2.048 Zeichen lang sein.
• Lokale Adressen sind erlaubt, damit sich die Zustellung testen lässt.
• Eine ungültige URL ergibt invalid_webhook_url.
• Ein unbekannter oder fremder Webhook ergibt webhook_not_found.
• Ohne Plus antwortet die Verwaltung mit plan_required.

Zustellung

Eventwerk sendet einen POST mit JSON-Rumpf. Der Rumpf enthält die Art, den Titel, den Text, den internen Link und den Zeitpunkt der Benachrichtigung.

{
  "kind": "registration_created",
  "title": "Neue Anmeldung",
  "body": "Anna hat sich für Herbstkonferenz angemeldet.",
  "link_path": "/dashboard/events/<eventID>/registrations",
  "created_at": "2026-10-25T12:00:00Z"
}

• Ein Zustellversuch hat ein Zeitlimit von 5 Sekunden.
• Jeder Webhook erhält höchstens zwei Versuche im Abstand von 500 Millisekunden.
• Eine Antwort mit Status 2xx gilt als erfolgreich.
• Es gibt keine dauerhafte Warteschlange. Nach einem Neustart gehen nicht zugestellte Aufrufe verloren.
• Fehler werden nur protokolliert. Der auslösende Vorgang, etwa eine Anmeldung, bleibt gültig.
• Die Reihenfolge der Zustellungen ist nicht garantiert.

Signatur prüfen

Berechnen Sie die HMAC-SHA256-Signatur über den rohen Rumpf, nicht über das neu serialisierte JSON. Vergleichen Sie die Signatur in konstanter Zeit mit dem Header.

import crypto from "node:crypto";

const expected =
  "sha256=" +
  crypto.createHmac("sha256", secret).update(rawBody).digest("hex");

const received = request.headers["x-eventwerk-signature"];

if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))) {
  return response.status(401).end();
}

Ereignisse