Webhooks

Webhooks let Lumicast notify your own server when things happen in your workspace — a display goes offline, a playlist is published, a campaign ends, and more. Your server receives an HTTP POST with a JSON payload and can react however you like.

Creating a webhook

1. Go to Workspace → Webhooks.
2. Click the + button.
3. Enter:
   • Name — anything you'll recognise it by
   • URL — the endpoint on your server that will receive the events
   • Secret (optional) — used to sign each payload so you can verify it really came from Lumicast
4. Choose which events this webhook subscribes to. Each webhook can listen to any number of events.
5. Save.

You can edit the URL, rotate the secret, or change the subscriptions at any time.

What your server receives

Every event is a POST request with a JSON body describing the change, plus these headers:

Header	Meaning
X-Lumicast-Event	The event type, formatted as <resource>.<action> (e.g. display.updated)
X-Lumicast-Resource-Type	The kind of resource the event is about
X-Lumicast-Resource-Id	The ID of that resource
X-Lumicast-Signature	HMAC-SHA256 of the JSON body, using your webhook secret (only sent if a secret is configured)

Verify the signature on your end by computing HMAC-SHA256(secret, rawBody) in hex and comparing it to the header — if they don't match, reject the request.

Delivery and retries

Lumicast expects your server to respond with a 2xx status within 5 seconds. If the request fails or times out, it's retried on this schedule: 15 s, 30 s, 1 min, 5 min, 30 min, 1 h. After that, the event is dropped.

Design your handler to be idempotent — the same event may arrive more than once on a slow or flaky network.

Full event reference

The complete list of event types, payload shapes, and examples lives in the API reference:

👉 Webhook event documentation

Use this alongside Lumicast's REST API documentation if you want to react to a webhook and then call back into Lumicast.