Create a webhook endpoint

By the end, your organization has an active endpoint that receives the chosen events at your https address, and you have stored the signing secret safely.

Steps#

In the portal#

1. Open Settings › Organization › Webhooks.
2. Click Create endpoint. The Create webhook endpoint dialog opens.
3. Under Endpoint URL, enter the address of your receiver, for example https://example.com/hooks/signage.
4. Under Subscribed events, choose the event types in the Search event … field. The field filters the catalog, and each choice appears as a chip above the field. At least one event is required.
5. Click Create.
6. The Signing secret — visible only now box appears. Click Copy secret and store the value where your receiver reads it. Only then click Got it.

Create becomes available only when an address is entered and at least one event is in the selection as a chip.

Through the API#

$TOKEN is the access token from signing in as Owner. An API key cannot carry the webhook permissions (see Authentication). $SZENERA_API is the base URL of your environment.

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"]
  }'

The response (status 201) contains the endpoint and, only in this response, the secret:

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

The secret cannot be retrieved afterward. If it gets lost, renew it (see Options).

The server checks the events list before it creates the endpoint. Allowed values are an exact event type, an area such as composition.*, or * for everything. An unknown name is 422 WebhookEndpoint.EventUnknown and is named in the response. A typo should stand out here and not end up as an endpoint that stays silent. GET /v1/webhooks/event-types returns the names that exist, see Fetch the event catalog through the API.

Options#

When you edit an endpoint, the signing secret stays unchanged. A deactivated endpoint keeps its address, events, and delivery history. Added events and a re-enabled endpoint take effect up to an hour later. Newly created endpoints take effect immediately.

Rules for the address and events#

• https only, public only. The address begins with https://. The server rejects localhost, ::1, names ending in .local, and the ranges 127., 10., 192.168., 169.254., and 172.16. through 172.31.. The response is status 422, WebhookEndpoint.UrlInvalid, both when creating and when changing.
• At least one event, known names. Allowed are an exact event type, an area such as composition.*, and *. A typo in the type is rejected with 422 WebhookEndpoint.EventUnknown, and so is a type that cannot be subscribed to.
• The package counts when you create an endpoint and when you renew the secret. Without webhooks in the package, creating an endpoint returns status 403, Billing.FeatureNotEntitled. In the portal, Create endpoint and Rotate secret are locked, while POST /v1/webhooks/{id}/rotate-secret remains possible through the API. Existing endpoints keep running.
• Permissions. Creating, changing, renewing, and deleting require the Owner role (webhook.create, webhook.update, webhook.delete). Owners and Managers see the list (webhook.list).

Check the result#

• The endpoint appears in the Webhook endpoints list with the status Active.
• After the next matching event, the Delivery log shows a row with the status Delivered and the response code of your server (for example “HTTP 200”).
• Your receiver has seen a request with the headers X-Signature, X-Event-Type, and X-Delivery-Id.

If something goes wrong#

Related#

• Verify the signature of a delivery
• Event types: organization, accounts, billing
• Fetch the event catalog through the API
• When no delivery arrives