# 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](rotate-secret.md), 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. |

```json
{
  "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](get.md) beschrieben.

```json
{
  "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

```bash
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`