# Fetch the event catalog through the API

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.

> **Type:** reference
> **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 call

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

```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" }
}
```

| 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](/changes/stability-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](/api/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](/webhooks/event-types-content-devices#what-never-arrives). |

`WebhookEndpoint.EventUnknown` is listed with the other webhook codes under [Error codes: devices, playback, notifications, operations](/api/error-codes-devices-operations).

## Related

- [Create a webhook endpoint](/webhooks/create-endpoint)
- [Event types: organization, accounts, billing](/webhooks/event-types-organization)
- [Event types: content, programs, devices, apps](/webhooks/event-types-content-devices)