Zum Inhalt springen
Szenera DeveloperHandbuch
Webhooks › Ereignisse › Den Ereigniskatalog über die API abrufen
Kapitel

Den Ereigniskatalog über die API abrufen

Sie legen Endpunkte aus einem eigenen System an oder zeigen die Auswahl in Ihrer Oberfläche: den Katalog als JSON holen, eine Ereignis-Liste prüfen, bevor der Server sie abweist.

3 Minuten LesezeitWebhooksStand: 25.10.2026

Auf dieser Seite

Bevor Sie loslegen

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 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.

Der Aufruf

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

{
  "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.

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.
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.

WebhookEndpoint.EventUnknown steht mit den übrigen Webhook-Codes unter Fehlercodes: Geräte, Wiedergabe, Meldungen, Betrieb.

Weiterführendes