Webhook event list
The event types for rooms, seats, stage and PK battles, when each is sent, and how delivery works.
Applies to: engine API v1
Webhooks are configured per event type: register a callback URL for each event you care about. An event type your project has no row for is simply never delivered, silently. GET /admin/projects/:id/callbacks returns the authoritative list in allowed_event_types; read it instead of hard-coding this table, because the list grows. Real payloads and field tables for the seat, stage, role, live and PK events are in Webhook events.
Delivery contract
- Respond with 2xx within 5 seconds.
- A failure (5xx, 408, timeout, network error) is retried, 4 attempts in total: immediately, then after 2 s, 4 s and 8 s. A 429 gets one retry (2 attempts in total).
- Any 4xx except 408 and 429 is permanent: no retry, the event is dead-lettered. 408 follows the full schedule; 429 is retried once, honouring
Retry-Afterup to 8 seconds. If your backend is not ready, answer 5xx. - If more than 20 deliveries to your URL are in flight at once, new events are dropped. Keep the handler fast and idempotent;
X-UTD-Stream-Attempt(1 to 4) tells a retry from a duplicate. - Verify the
X-UTD-Stream-Signatureheader (sha256=plus the HMAC-SHA256 of the raw body, keyed with your project's callback secret) before trusting any field. X-UTD-Stream-App-Idsays which project the event is for; read it first if one endpoint serves several projects.
Room events can be delivered in two payload shapes, selected per project with callback_schema. v1 (default) carries the media server's native ids; v2 uses neutral id prefixes (rid_, pid_, tid_) and a fixed, documented key set. The unique tail of every id is identical in both, so you can correlate across a switch. New integrations should use v2.
Rooms and tracks
| Event | Sent when |
|---|---|
room_started | A room is created |
room_finished | A room is closed |
participant_joined | A participant connects |
participant_left | A participant disconnects |
track_published | A participant starts publishing audio or video |
track_unpublished | A participant stops publishing |
participant_role_changed | Someone was promoted or demoted |
Seats, comments and speaker requests (audio rooms)
| Event | Sent when |
|---|---|
seat_taken, seat_left, seat_locked, seat_unlocked | The seat grid changes |
comments_locked, comments_unlocked | Room chat was locked or unlocked |
speaker_request_received, speaker_request_cancelled, speaker_request_approved, speaker_request_rejected | Microphone requests |
speaker_invitation_sent, speaker_invitation_accepted, speaker_invitation_declined, speaker_invitation_expired | Microphone invitations |
Live streams
| Event | Sent when |
|---|---|
stage_joined, stage_left, stage_request | Stage changes |
stage_invitation_sent, stage_invitation_accepted, stage_invitation_declined, stage_invitation_expired | Stage invitations |
live_ended | A live stream ended |
pk_invited, pk_started, pk_ended | PK battles. Subscribe to pk_started before you implement scoring: scoring is server-side only and this event is how your backend learns the battle_id. |
import crypto from "node:crypto";
// Mount with a raw body parser so you hash the exact bytes received:
// app.post("/webhooks/utd", express.raw({ type: "application/json" }), handler)
function verifyWebhook(rawBody, signatureHeader, callbackSecret) {
if (!signatureHeader) return false;
const expected = "sha256=" + crypto.createHmac("sha256", callbackSecret).update(rawBody).digest("hex");
const a = Buffer.from(signatureHeader);
const b = Buffer.from(expected);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}Ready to build with UTD?
Create your account, fund your master wallet, and turn on the services you need.