Developer guide

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-After up 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-Signature header (sha256= plus the HMAC-SHA256 of the raw body, keyed with your project's callback secret) before trusting any field.
  • X-UTD-Stream-App-Id says 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

EventSent when
room_startedA room is created
room_finishedA room is closed
participant_joinedA participant connects
participant_leftA participant disconnects
track_publishedA participant starts publishing audio or video
track_unpublishedA participant stops publishing
participant_role_changedSomeone was promoted or demoted

Seats, comments and speaker requests (audio rooms)

EventSent when
seat_taken, seat_left, seat_locked, seat_unlockedThe seat grid changes
comments_locked, comments_unlockedRoom chat was locked or unlocked
speaker_request_received, speaker_request_cancelled, speaker_request_approved, speaker_request_rejectedMicrophone requests
speaker_invitation_sent, speaker_invitation_accepted, speaker_invitation_declined, speaker_invitation_expiredMicrophone invitations

Live streams

EventSent when
stage_joined, stage_left, stage_requestStage changes
stage_invitation_sent, stage_invitation_accepted, stage_invitation_declined, stage_invitation_expiredStage invitations
live_endedA live stream ended
pk_invited, pk_started, pk_endedPK 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.
verify.js (Node)
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);
}

UTD দিয়ে গড়তে প্রস্তুত?

আপনার অ্যাকাউন্ট তৈরি করুন, মাস্টার ওয়ালেট ফান্ড করুন, এবং প্রয়োজনীয় সার্ভিসগুলো চালু করুন।