# Stream events

Vabu tells your server when a stream goes live, drops or ends, when an asset is ready and when someone's access changes. You get these as [webhooks](https://docs.vabu.live/concepts/webhooks.md), signed and retried like every other event, so your app does not need to poll.

Register an endpoint with `POST /v1/webhook_endpoints` and ask for `streams.*` and `access.*`. The envelope, the signature check and the retry schedule are on the [webhooks](https://docs.vabu.live/concepts/webhooks.md) page. Every event type and its fields are in the [event catalogue](https://docs.vabu.live/events/index.md).

The events carry the resource as the API shows it, without secrets. The stream key, the upload address and the SRT passphrase are never in an event. `data.previous_attributes` shows the old values of whatever changed.

## Live streams

| Event | When | What to do |
|---|---|---|
| `streams.live_stream.created` | A live stream was created | Store its id next to your venue. |
| `streams.live_stream.updated` | Settings, the key, simulcast targets or playback ids changed, or an encoder connected (`status: "connecting"`) | Refresh what you show. |
| `streams.live_stream.active` | The encoder is sending video | Show the stream as live and send your "we are live" message. |
| `streams.live_stream.disconnected` | The encoder dropped. It can come back within the `reconnect_window`. | Show "we will be right back". Alert the crew if you want to. |
| `streams.live_stream.idle` | The broadcast ended | Show the stream as over. Offer the replay when you have one. |
| `streams.live_stream.unhealthy` | The network a live stream runs on is struggling or down. `data.object.health` says which and why. | Viewers move to the standby by themselves. Tell the crew if you want to. |
| `streams.live_stream.recovered` | That network is healthy again | Clear the alert. |
| `streams.live_stream.deleted` | A live stream was deleted | Remove it from your lists. |

Use these events for what the page shows. Do not use them to decide who may watch. That is the job of an entitlement and a session.

## Assets, clips and uploads

| Event | When | What to do |
|---|---|---|
| `streams.asset.created` | An asset or a clip was created, or an upload produced one | Record the asset id. |
| `streams.asset.ready` | The asset can be played | Show it and tell your customers. |
| `streams.asset.errored` | The video could not be processed. `data.object.error` says why. | Ask for a new file. |
| `streams.asset.updated` | Metadata, the external id or playback ids changed | Refresh what you show. |
| `streams.asset.deleted` | An asset was deleted | Remove it from your lists. |
| `streams.clip.created` | A clip was created | Record it. |
| `streams.upload.asset_created` | An upload finished and its asset exists | Link the upload to your own record. |

## Access

| Event | When | What to do |
|---|---|---|
| `access.entitlement.granted` | Someone was given access | Update your records. |
| `access.entitlement.revoked` | Access was taken away | Update your records. |
| `access.entitlement.suspended` and `access.entitlement.resumed` | Access was paused and restored | Update your records. |
| `access.entitlement.expired` | The end date passed | Offer a renewal. |
| `access.entitlement.extended` | A source moved the end date later | Update your records. |

## Handling events well

- An event can arrive more than once and out of order. Store the event `id` and skip repeats. Compare `created_at`, or fetch the resource, when order matters.
- Answer with a `2xx` fast and do slow work afterwards.
- Check the signature on every delivery. See [verify the signature](https://docs.vabu.live/concepts/webhooks.md#verify-the-signature).
- In test mode, events come from your test streams and test entitlements to your test endpoints only.

## Not available yet

Events for viewer counts, watch time and quality are on [What's coming](https://docs.vabu.live/whats-coming.md).