Skip to content
Szenera DeveloperDocs
Webhooks › Events › Fetch the event catalog through the API
Chapters

Fetch the event catalog through the API

You create endpoints from your own system or show the selection in your own interface: fetch the catalog as JSON and check a list of events before the server rejects it.

3 minute readWebhooksUpdated: 10/25/2026

On this page

Before you start

For
Anyone who creates endpoints from their own system or shows a selection of events in their own interface.
Prerequisite
A sign-in with the permission webhook.list. This is a session permission, and no key carries it.

The catalog of subscribable events is not only in the portal: GET /v1/webhooks/event-types returns it as JSON, with plain-language names, a description, and a complete example body for each event. With it, you check a list of events before the server rejects it and build your own selection without typing names.

The call

curl -sS "$SZENERA_API/v1/webhooks/event-types" \
  -H "Authorization: Bearer $TOKEN"
Parameter Values Default
locale de, en de

Only these two languages are supported. They are the ones in which the plain texts are complete. A full language code would promise more than exists.

What comes back

{
  "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" }
}
Field Meaning
items[].type the string you subscribe to. It arrives in X-Event-Type with every delivery
items[].area the area, that is, the first segment before the dot. This is the value you use when subscribing to a whole area
items[].label, .areaLabel, .description plain text for your own interface, in the language from locale
items[].exampleBody the complete body of a delivery, not an excerpt. null where no example can be derived from the contract. None is invented
areas the areas that have subscribable events, with their plain text
headers the names of the three headers that every delivery carries

The body of a delivery is the payload of the event itself and nothing around it: the event type and the delivery identifier are in the headers, not in the body. So exampleBody is exactly what your receiver will see.

What you need it for

Check before the server rejects. When you create or change an endpoint, the platform checks every entry of the events list. Exactly three forms are allowed:

Form Meaning
composition.scene.published exactly this event type
composition.* every type of the area composition. The area must be in areas
* everything that can be subscribed to

Everything else is 422 WebhookEndpoint.EventUnknown, and the response lists the names it does not recognize under details.unknownEvents (up to twenty). A typo should stand out on input and not end up as an endpoint that stays silent for years, without a failed attempt and without an entry in the delivery log.

Choose without the portal. If you build your own interface, take names, areas, and descriptions from here instead of maintaining them. That way they never go stale.

An example for testing. exampleBody is a valid body. Use it to feed your receiver before the event first occurs for real.

Stability

The operation carries x-stability: beta. The shape of this list may still change until it has gone through a cycle without a breaking change. The names of the events themselves are not affected. What beta promises and what it does not is described under Stability classes and sunset.

If something goes wrong

Symptom Meaning Solution
403 on the call The credential is an API key. The webhook permissions are reserved for sessions. Sign in with an account, see Authentication.
422 WebhookEndpoint.EventUnknown An entry in events fits none of the three forms. Check the reported name against items[].type and areas[].area.
An expected event is missing from the catalog and cannot be subscribed to The catalog lists only what is raised in the context of your organization. See What never arrives.

WebhookEndpoint.EventUnknown is listed with the other webhook codes under Error codes: devices, playback, notifications, operations.