# 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](https://api.lumicast.com/webhook-docs)**

Use this alongside Lumicast's [REST API documentation](https://api.lumicast.com/docs) if you want to react to a webhook and then call back into Lumicast.