Webhook-Endpunkt hinzufügen

POST /v1/webhook-endpoints · Berechtigung webhook-endpoints:write · alle Tarife

Fügt einen Endpunkt hinzu, der die Ereignisse der Umgebung empfängt, signiert nach dem Standard-Webhooks-v1-Schema. Zustellungen erfolgen mindestens einmal: Dedupliziere sie anhand des Headers webhook-id.

Signiergeheimnis. Die Antwort enthält signing_secret (idp_whsec_…) genau einmal, mit Cache-Control: no-store. Es kann nicht erneut abgerufen werden; speichern Sie es sofort. Eine mit demselben Idempotency-Key wiederholte Anfrage liefert den Endpunkt ohne Geheimnis und mit secret_redacted: true. Verwenden Sie Signiergeheimnis rotieren, wenn es verloren gegangen oder offengelegt wurde.
URL. Nur https, kein Port oder Port 443, keine Benutzerinformationen oder Fragmente, kein IP-Literal, höchstens 2.048 Zeichen. Weiterleitungen werden nicht verfolgt.
Ereignisse. event_types listet Ereignistypen aus dem Katalog auf; eine leere Liste bedeutet alle Typen außer den umfangreichen.
Limit. Eine Umgebung kann höchstens Free 3, Startup 20, Business 20 oder Enterprise 50 aktivierte Endpunkte haben.

Anfrage

Feld	Typ	Pflicht	Beschreibung
`url`	string	ja	Empfänger-URL (Regeln oben).
`key`	string	nein	Stabiler Schlüssel, in der Umgebung eindeutig: `[a-z0-9][a-z0-9_-]{0,63}`. Standard `endpoint-<letzte 8 Zeichen der ID>`.
`description`	string	nein	Höchstens 500 Zeichen.
`event_types`	array	nein	Ereignistypen aus dem Katalog, höchstens 100, ohne Duplikate. Leer oder fehlend: alle Typen außer den umfangreichen.
`event_schema_versions`	object	nein	Ereignistyp → Schemaversion. Ein nicht aufgeführter Typ wird mit seiner ältesten unterstützten Version gesendet.
`payload_mode`	string	nein	`thin` (Standard: IDs, geänderte Feldnamen und Statusfelder, keine personenbezogenen Daten) oder `full` (die Darstellung der Ressource in der Management-API).
`rate_limit_per_second`	integer	nein	1–1.000 Zustellungen pro Sekunde an diesen Endpunkt; Standard 50.
`status`	string	nein	`enabled` (Standard) oder `disabled_by_user`.
`Idempotency-Key`	header	nein	Liefert die Antwort (ohne Geheimnis) erneut für eine wiederholte Anfrage mit demselben Schlüssel.

{
  "url": "https://hooks.example.com/keenauth",
  "key": "crm-sync",
  "description": "CRM sync",
  "event_types": ["user.created", "user.updated"]
}

Antwort

201 Created mit dem Endpunkt, ETag mit seiner Version und dem Geheimnis. Die übrigen Felder sind unter Webhook-Endpunkt abrufen beschrieben.

{
  "id": "whe_01k8a3m5q7t9v1w3x5y7z9b2c4",
  "key": "crm-sync",
  "url": "https://hooks.example.com/keenauth",
  "description": "CRM sync",
  "event_types": ["user.created", "user.updated"],
  "event_schema_versions": {},
  "payload_mode": "thin",
  "status": "enabled",
  "rate_limit_per_second": 50,
  "previous_secret_expires_at": null,
  "last_success_at": null,
  "failing_since": null,
  "version": 1,
  "created_at": "2026-10-26T09:00:00Z",
  "updated_at": "2026-10-26T09:00:00Z",
  "signing_secret": "idp_whsec_<secret>"
}

Fehler

HTTP	Code	Wann
400	`unknown_field`	Der Body enthält ein Feld, das oben nicht aufgeführt ist.
403	`quota_exceeded`	Die Umgebung hat bereits die Anzahl aktivierter Endpunkte ihres Tarifs erreicht oder ihr Tarif ist nicht bekannt.
409	`conflict`	Ein anderer Endpunkt der Umgebung hat diesen `key`.
422	`validation_failed`	`/url required`, `/url invalid_webhook_url`, `/key invalid`, `/description too_long`, `/event_types unknown_event_type`, `/event_types duplicate`, `/event_types too_many`, `/event_schema_versions unsupported_schema_version`, `/payload_mode invalid`, `/rate_limit_per_second out_of_range`, `/status invalid`.
422	`idempotency_key_reuse`	Der `Idempotency-Key` wurde für eine andere Anfrage verwendet.
401	`unauthenticated`	Die Berechtigungsnachweise fehlen, sind ungültig oder widerrufen.
403	`insufficient_permissions`	Die Berechtigungsnachweise enthalten nicht `webhook-endpoints:write`.
429	`rate_limited`	Das Ratenlimit wurde überschritten; wiederholen Sie die Anfrage nach der Zeit aus `Retry-After`.
503	`service_unavailable`	Die Verwaltung von Webhooks ist vorübergehend nicht verfügbar; wiederholen Sie die Anfrage nach der Zeit aus `Retry-After`.

Beispiel

curl -X POST https://api.eu.keenauth.com/v1/webhook-endpoints \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b2d4f6a-1c3e-4a5b-8d7f-0e2c4a6b8d1f" \
  -d '{"url":"https://hooks.example.com/keenauth","key":"crm-sync","event_types":["user.created","user.updated"]}'

CLI: keenauth webhook-endpoints create --url https://hooks.example.com/keenauth --key crm-sync --event-types user.created,user.updated