# Den Ereigniskatalog über die API abrufen

Der Katalog der abonnierbaren Ereignisse steht nicht nur im Portal: `GET /v1/webhooks/event-types` liefert ihn als JSON, mit Klartext-Namen, Beschreibung und einem vollständigen Beispiel-Rumpf je Ereignis. Damit prüfen Sie eine Ereignis-Liste, bevor der Server sie abweist, und bauen eine eigene Auswahl, ohne Namen abzutippen.

> **Typ:** nachschlagen
> **Für wen:** Wer Endpunkte aus einem eigenen System anlegt oder eine Auswahl der Ereignisse in seiner eigenen Oberfläche zeigt.
> **Voraussetzung:** eine Anmeldung mit dem Recht `webhook.list` — das ist ein Sitzungsrecht, kein Schlüssel trägt es

## Der Aufruf

```bash
curl -sS "$SZENERA_API/v1/webhooks/event-types" \
  -H "Authorization: Bearer $TOKEN"
```

| Parameter | Werte | Vorgabe |
|---|---|---|
| `locale` | `de`, `en` | `de` |

Nur diese beiden Sprachen: Es sind die, in denen die Klartexte vollständig vorliegen. Ein voller Sprachcode verspräche mehr, als es gibt.

## Was zurückkommt

```json
{
  "items": [
    {
      "type": "composition.scene.published",
      "area": "composition",
      "areaLabel": "Szenen",
      "label": "Szene veröffentlicht",
      "description": "Die Szene geht auf die Displays; betroffene Player bekommen den neuen Stand.",
      "exampleBody": { "sceneId": "scn_01KJPX8NH0SZENE00000000001", "sceneVersionId": "scv_01KJPX8NH0FASSUNG000000001", "versionNumber": 8, "contentHash": "sha256:1f0c…" }
    }
  ],
  "areas": [{ "area": "composition", "label": "Szenen" }],
  "headers": { "signature": "X-Signature", "eventType": "X-Event-Type", "deliveryId": "X-Delivery-Id" }
}
```

| Feld | Bedeutung |
|---|---|
| `items[].type` | die Zeichenkette, die Sie abonnieren; sie kommt bei jeder Zustellung in `X-Event-Type` an |
| `items[].area` | der Bereich, also das erste Segment vor dem Punkt — der Wert, auf den ein Bereichs-Abo zeigt |
| `items[].label`, `.areaLabel`, `.description` | Klartext für Ihre eigene Oberfläche, in der Sprache aus `locale` |
| `items[].exampleBody` | der **vollständige** Rumpf einer Zustellung, nicht ein Ausschnitt; `null`, wo sich aus dem Vertrag kein Beispiel ableiten lässt — erfunden wird keines |
| `areas` | die Bereiche, in denen es abonnierbare Ereignisse gibt, mit ihrem Klartext |
| `headers` | die Namen der drei Kopfzeilen, die jede Zustellung trägt |

Der Rumpf einer Zustellung ist die Nutzlast des Ereignisses selbst und nichts darum herum: Ereignisart und Zustell-Kennung stehen in den Kopfzeilen, nicht im Rumpf. Damit ist `exampleBody` genau das, was Ihr Empfänger sehen wird.

## Wofür Sie ihn brauchen

**Prüfen, bevor der Server abweist.** Beim Anlegen und Ändern eines Endpunkts prüft die Plattform jeden Eintrag der Liste `events`. Erlaubt sind genau drei Formen:

| Form | Bedeutung |
|---|---|
| `composition.scene.published` | genau diese Ereignisart |
| `composition.*` | jede Art des Bereichs `composition` — der Bereich muss in `areas` stehen |
| `*` | alles, was abonnierbar ist |

Alles andere ist `422 WebhookEndpoint.EventUnknown`, und die Antwort nennt unter `details.unknownEvents` die Namen, die sie nicht kennt (bis zu zwanzig). Ein Tippfehler soll bei der Eingabe auffallen und nicht als Endpunkt enden, der jahrelang stumm bleibt, ohne Fehlversuch und ohne Eintrag im Zustellprotokoll.

**Auswählen ohne Portal.** Wer eine eigene Oberfläche baut, holt sich Namen, Bereiche und Beschreibungen von hier, statt sie zu pflegen. Sie altern damit nicht.

**Ein Beispiel für den Test.** `exampleBody` ist ein gültiger Rumpf: Damit füttern Sie Ihren Empfänger, bevor das Ereignis zum ersten Mal wirklich eintritt.

## Stabilität

Die Operation trägt `x-stability: beta`. Die Form dieser Liste darf sich noch bewegen, bis sie einen Zyklus ohne Bruch hinter sich hat; die Namen der Ereignisse selbst sind davon nicht betroffen. Was `beta` zusagt und was nicht, steht unter [Stabilitätsklassen und Auslauf](/de/changes/stability-and-sunset).

## Wenn etwas nicht klappt

| Symptom | Bedeutung | Lösung |
|---|---|---|
| `403` auf den Aufruf | Der Ausweis ist ein API-Schlüssel; die Webhook-Rechte sind Sitzungen vorbehalten. | Mit einem Konto anmelden, siehe [Anmeldung](/de/api/authentication). |
| `422 WebhookEndpoint.EventUnknown` | Ein Eintrag in `events` passt in keine der drei Formen. | Den genannten Namen gegen `items[].type` und `areas[].area` prüfen. |
| Ein erwartetes Ereignis fehlt im Katalog und lässt sich nicht abonnieren | Der Katalog führt nur, was im Kontext Ihrer Organisation entsteht. | Siehe [Was nie ankommt](/de/webhooks/event-types-content-devices#was-nie-ankommt). |

`WebhookEndpoint.EventUnknown` steht mit den übrigen Webhook-Codes unter [Fehlercodes: Geräte, Wiedergabe, Meldungen, Betrieb](/de/api/error-codes-devices-operations).

## Weiterführendes

- [Einen Webhook-Endpunkt anlegen](/de/webhooks/create-endpoint)
- [Ereignistypen: Organisation, Konten, Abrechnung](/de/webhooks/event-types-organization)
- [Ereignistypen: Inhalte, Programme, Geräte, Apps](/de/webhooks/event-types-content-devices)