Webhooks Overview
Native Frame uses webhooks in two different ways, and it's worth knowing which is which because they behave very differently.
| Event notifications | Program-states integration | |
|---|---|---|
| Purpose | Tell you something happened | Ask your integration for a verdict |
| Direction | One-way (fire-and-forget) | Request/response — your reply drives platform behavior |
| Delivery | Async, fanned out, retried (exponential backoff), with delivery history | Synchronous, in the stream lifecycle path |
| Webhooks registered | Many — you register/manage URLs | Exactly one registered webhook |
| What your response does | Nothing (only the HTTP status matters) | stop / needAuth / appData can veto a start, tear down a stream, or reject a peer |
1. Event notifications
You register one or more webhook endpoints and Native Frame delivers events to them as things happen — asynchronously, with retries and full delivery history. Your endpoint just needs to accept the delivery (the response body isn't acted on). Registration and management are done through the dashboard, or via the Events API (GET / PUT / DELETE /events/v2/webhook/{name}). See Webhooks to set one up.
2. Program-states integration
This is the verdict path used for stream-lifecycle decisions and lifecycle notifications. Native Frame calls your single registered webhook synchronously; for some events your response decides what happens next.
Events fall into two kinds.
Respondable (verdict) events — your response can set stop, needAuth, appData:
| Event | What it's for |
|---|---|
starting | Admission gate. Fired synchronously on start-stream/start-broadcast. Return stop (at program, stream, or token level) to reject the broadcast before any session is created. Fails closed — if the webhook call itself fails, the start is blocked. |
polling | Ongoing verdict while a token is connected — return stop to tear the token/stream down. |
| token / consumer join + poll events | Per-participant admission/verdict. |
Notification events — informational, no response needed:
| Event | Fired when |
|---|---|
producer-format-started / producer-format-ended | A transcode variant becomes available / unavailable — see the Format Availability guide. |
closed | Fire-and-forget on end-stream/end-broadcast for each active stream. |
peer-left | A participant (producer or consumer) has left the stream. |
manifest-ready, disconnected, etc. | Various lifecycle notifications. |
Delivery shape
Program-states events are delivered nested, as program-states-v2 — programs → streams → producing/consuming → token.event. Your response is sparse: only include the events you want to act on; omitted events accept defaults (stop=false, needAuth=false).
events format — not yet available via webhooksThe platform also defines a flat, event-based payload (event: "events"), configured per project in the auth service and delivered only via direct integration — it is not available through the events-service webhook, and only a few integrations use it. Integrate against the nested program-states-v2 shape.
Which one do I need?
- "Tell me when X happens" (recordings ready, analytics, generic notifications) → register an event-notification webhook.
- "Let me approve/deny streams, or know about live stream state and formats" → you're on the program-states integration (private + program-states auth flow). Format availability, the start admission gate, and polling verdicts all arrive here.
For the payload formats, the response contract (stop / needAuth / appData), and the full event catalog, see the Webhooks API reference.