# Einen Webhook-Endpunkt anlegen

Am Ende hat Ihre Organisation einen aktiven Endpunkt, der die gewählten Ereignisse an Ihre https-Adresse bekommt, und Sie haben das Signatur-Secret sicher abgelegt.

> **Typ:** anleitung
> **Für wen:** Wer ein eigenes System an Ereignisse der Plattform anschließen will.
> **Voraussetzung:** Ein Paket, das Webhooks enthält (ab Premium); die Rolle Inhaber; eine öffentlich erreichbare https-Adresse, die POST-Anfragen annimmt.
> **Ort:** **Einstellungen › Organisation › Webhooks** — oder die API unter `/v1/webhooks`.

## Schritte

### Im Portal

1. Öffnen Sie **Einstellungen › Organisation › Webhooks**.
2. Klicken Sie auf **Endpunkt anlegen**. Der Dialog **Webhook-Endpunkt anlegen** öffnet sich.
3. Tragen Sie unter **Endpunkt-URL** die Adresse Ihres Empfängers ein, zum Beispiel `https://example.com/hooks/signage`.
4. Wählen Sie unter **Abonnierte Ereignisse** im Feld **Ereignis suchen …** die Ereignistypen. Das Feld filtert den Katalog, jede Wahl legt sich als Chip über das Feld; mindestens ein Ereignis ist nötig.
5. Klicken Sie auf **Anlegen**.
6. Der Kasten **Signatur-Secret — nur jetzt sichtbar** erscheint. Klicken Sie auf **Secret kopieren** und legen Sie den Wert dort ab, wo Ihr Empfänger ihn liest. Erst dann **Verstanden**.

![Der Dialog Webhook-Endpunkt anlegen mit dem Feld Endpunkt-URL (1), der Auswahl Abonnierte Ereignisse samt Suchfeld Ereignis suchen … (2) und der Schaltfläche Anlegen (3)](/de/webhooks/bilder/b1330581-create-endpoint.png)

_**Anlegen** wird erst wählbar, wenn eine Adresse steht und mindestens ein Ereignis als Chip in der Auswahl liegt._

### Über die API

`$TOKEN` ist das Zugriffstoken einer Anmeldung als Inhaber — ein API-Schlüssel kann die Webhook-Rechte nicht tragen (siehe [Anmeldung](/de/api/authentication)); `$SZENERA_API` ist die [Basis-URL](/de/api/base-url-and-stability) Ihrer Umgebung.

```bash
curl -X POST "$SZENERA_API/v1/webhooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://warenwirtschaft.example.com/hooks/signage",
    "events": ["composition.scene.published", "scheduling.playlist.updated", "media-library.asset.ready"]
  }'
```

Die Antwort (Status 201) enthält den Endpunkt und — nur in dieser Antwort — das Secret:

```json
{
  "endpoint": {
    "id": "whk_01KPR20K40WEBHK00000000001",
    "tenantId": "tnt_01KERPXZM0ADERAPTHEKE00001",
    "url": "https://warenwirtschaft.example.com/hooks/signage",
    "events": ["composition.scene.published", "scheduling.playlist.updated", "media-library.asset.ready"],
    "active": true,
    "consecutiveFailures": 0,
    "lastDeliveryAt": null,
    "lastFailureAt": null,
    "createdById": "usr_01KFB7QPW0TEAM000000000002",
    "createdAt": "2026-04-21T13:00:00.000Z"
  },
  "secret": "whsec_9tR4mZpQ2xVs7KdHc3JnFb6yWa8EgTu1"
}
```

Das Secret ist danach nicht mehr abrufbar; geht es verloren, erneuern Sie es (siehe Optionen).

Die Liste `events` prüft der Server, bevor er den Endpunkt anlegt: Erlaubt sind eine genaue Ereignisart, ein Bereich als `composition.*` oder `*` für alles. Ein unbekannter Name ist `422 WebhookEndpoint.EventUnknown` und wird in der Antwort genannt — ein Tippfehler soll hier auffallen und nicht als Endpunkt enden, der stumm bleibt. Welche Namen es gibt, liefert `GET /v1/webhooks/event-types`, siehe [Den Ereigniskatalog über die API abrufen](/de/webhooks/fetch-event-catalog).

## Optionen

| Aufgabe | Im Portal | Über die API |
|---|---|---|
| Adresse oder Ereignisse ändern | **Bearbeiten** → Dialog **Webhook bearbeiten** → **Speichern** | `PATCH /v1/webhooks/{id}` mit `url` und/oder `events` |
| Endpunkt anhalten oder fortsetzen | **Deaktivieren** / **Aktivieren** | `PATCH /v1/webhooks/{id}` mit `{"active": false}` bzw. `{"active": true}` |
| Secret erneuern | **Secret rotieren** → neuer Kasten **Signatur-Secret — nur jetzt sichtbar** | `POST /v1/webhooks/{id}/rotate-secret` → Antwort `{"secret": "whsec_…"}` |
| Endpunkt entfernen | **Löschen** → Dialog **Webhook-Endpunkt löschen?** → **Löschen** | `DELETE /v1/webhooks/{id}` → `{"deleted": true}` |
| Endpunkte auflisten | Liste unter **Webhook-Endpunkte** | `GET /v1/webhooks?limit=50` (Blättern mit `cursor`) |

Beim Bearbeiten bleibt das Signatur-Geheimnis unverändert. Ein deaktivierter Endpunkt behält Adresse, Ereignisse und Zustell-Historie. Ergänzte Ereignisse und ein wieder eingeschalteter Endpunkt werden bis zu eine Stunde später wirksam; neu angelegte Endpunkte sofort.

### Regeln für Adresse und Ereignisse

- **Nur https, nur öffentlich.** Die Adresse beginnt mit `https://`; abgewiesen werden `localhost`, `::1`, Namen auf `.local` sowie `127.`, `10.`, `192.168.`, `169.254.` und `172.16.` bis `172.31.` — Status 422, `WebhookEndpoint.UrlInvalid`, beim Anlegen wie beim Ändern.
- **Mindestens ein Ereignis, bekannte Namen.** Erlaubt sind ein genauer Ereignistyp, ein Bereich wie `composition.*` und `*`. Ein Tippfehler im Typ wird mit `422 WebhookEndpoint.EventUnknown` abgewiesen, ebenso ein Typ, der nicht abonnierbar ist.
- **Das Paket zählt beim Anlegen und beim Erneuern des Secrets.** Ohne Webhooks im Paket antwortet das Anlegen mit Status 403, `Billing.FeatureNotEntitled`; im Portal sind **Endpunkt anlegen** und **Secret rotieren** gesperrt, über die API bleibt `POST /v1/webhooks/{id}/rotate-secret` möglich. Bestehende Endpunkte laufen weiter.
- **Rechte.** Anlegen, Ändern, Erneuern und Löschen brauchen die Rolle Inhaber (`webhook.create`, `webhook.update`, `webhook.delete`); die Liste sehen Inhaber und Manager (`webhook.list`).

## Ergebnis prüfen

- Der Endpunkt steht in der Liste **Webhook-Endpunkte** mit Status **Aktiv**.
- Nach dem nächsten passenden Ereignis zeigt das **Zustell-Log** eine Zeile mit Status **Zugestellt** und dem Antwortcode Ihres Servers (etwa „HTTP 200“).
- Ihr Empfänger hat eine Anfrage mit den Kopfzeilen `X-Signature`, `X-Event-Type` und `X-Delivery-Id` gesehen.

## Wenn etwas nicht klappt

| Symptom | Bedeutung | Lösung |
|---|---|---|
| Status 422, `WebhookEndpoint.UrlInvalid` | Adresse ist nicht https oder zeigt auf ein privates Netz | Öffentliche https-Adresse verwenden |
| Status 403, `Billing.FeatureNotEntitled`; im Portal sind **Endpunkt anlegen** und **Secret rotieren** gesperrt | Ihr Paket enthält keine Webhooks | Paket wechseln; bestehende Endpunkte lassen sich weiter bearbeiten, abschalten und löschen |
| Status 403, `Permission.Denied` | Ihr Konto hat nicht die Rolle Inhaber, oder Sie rufen mit einem API-Schlüssel auf | Als Inhaber anmelden; Zugriffstoken einer Anmeldung statt API-Schlüssel |
| Status 422, `WebhookEndpoint.EventUnknown` | Ein Eintrag in `events` steht in keiner der drei erlaubten Formen; `details.unknownEvents` nennt ihn | Namen gegen den [Ereigniskatalog](/de/webhooks/fetch-event-catalog) prüfen |
| Endpunkt aktiv, aber nie eine Zustellung | Ereignis tritt nicht ein oder Abonnement noch nicht wirksam | Siehe [Wenn keine Zustellung ankommt](/de/webhooks/troubleshooting) |

## Weiterführendes

- [Die Signatur einer Zustellung prüfen](/de/webhooks/verify-signature)
- [Ereignistypen: Organisation, Konten, Abrechnung](/de/webhooks/event-types-organization)
- [Den Ereigniskatalog über die API abrufen](/de/webhooks/fetch-event-catalog)
- [Wenn keine Zustellung ankommt](/de/webhooks/troubleshooting)