مرجع المطوّرين

أحداث الويب‌هوك

كل حدث يبعته محرّك UTD Stream لباكندك — بحمولته الحقيقية وحقوله المضمونة.

رجوع لمنتجات المطوّرين

تحقّق من التوقيع أولاً

كل طلب بيحمل توقيعًا بسرّك. تحقّق منه قبل ما تثق في أي حقل — الحمولة جاية من الشبكة، مش من عندك.

التسليم مضمون بإعادة محاولة

فشل التسليم بيتعاد 3 مرات (2s · 4s · 8s). يعني تقدر تبني عليها حالة، مش تأكيدًا بس.

ردّك بـ4xx بيوقف كل شيء

أي رد 4xx بيلغي إعادة المحاولة فورًا ويروح الحدث للرسائل الميتة. لو باكندك مش جاهز، ردّ 5xx عشان تاخد إعادة محاولة.

الترويسات

على كل تسليم، من غير ما تفتح الحمولة.

الترويسة	المعنى
`X-UTD-Stream-Signature`string	sha256=<hmac> over the raw body, keyed with your callback secret. Verify it before trusting anything.
`X-UTD-Stream-Event`string	The event name, so you can route without parsing the body first.
`X-UTD-Stream-Attempt`string	1 on the first delivery, 2..4 on retries. Use it to tell a retry from a duplicate event.
`X-UTD-Stream-App-Id`string	Your app id, when the project has one.

المنصّة والأدوار

طلبات الصعود، الدعوات، ومن غيّر دور مين.

stage_request

An audience member asks to come on stage.

الحقل	المعنى
`room.name`string	Your room id, exactly as you created it.
`room.sid`string	The media server's own room id. Changes if the room is recreated.
`participant.identity`string	Who asked.

stage_request.json

{
  "event": "stage_request",
  "room": { "name": "114", "sid": "RM_Lfzv9uoLpyMs" },
  "participant": { "identity": "48" }
}

stage_joined

A participant is put on stage — by a host, or by accepting an invitation.

الحقل	المعنى
`room.name`string	Your room id, exactly as you created it.
`room.sid`string	The media server's own room id. Changes if the room is recreated.
`participant.identity`string	Who joined the stage.
`participant.added_by`string	Who put them there.

stage_joined.json

{
  "event": "stage_joined",
  "room": { "name": "114", "sid": "RM_Lfzv9uoLpyMs" },
  "participant": { "identity": "48", "added_by": "148" }
}

stage_left

A participant leaves the stage, or a host removes them.

الحقل	المعنى
`room.name`string	Your room id, exactly as you created it.
`room.sid`string	The media server's own room id. Changes if the room is recreated.
`participant.identity`string	Who left the stage.
`participant.removed_by`string	Who removed them. Equals identity when they left on their own.

stage_left.json

{
  "event": "stage_left",
  "room": { "name": "114", "sid": "RM_Lfzv9uoLpyMs" },
  "participant": { "identity": "48", "removed_by": "148" }
}

stage_invitation_sent

A host invites someone to the stage.

الحقل	المعنى
`room.name`string	Your room id, exactly as you created it.
`room.sid`string	The media server's own room id. Changes if the room is recreated.
`participant.identity`string	Who was invited.
`invitation.id`string	Invitation id — carried by the accept / decline / expire events.
`invitation.inviter_identity`string	Who sent it.
`invitation.resent`boolean	true when this re-sends an invitation that was still open.

stage_invitation_sent.json

{
  "event": "stage_invitation_sent",
  "room": { "name": "114", "sid": "RM_Lfzv9uoLpyMs" },
  "participant": { "identity": "48" },
  "invitation": { "id": "inv_3f2a…", "inviter_identity": "148", "resent": false }
}

stage_invitation_accepted

The invited participant accepts. A stage_joined follows.

الحقل	المعنى
`room.name`string	Your room id, exactly as you created it.
`room.sid`string	The media server's own room id. Changes if the room is recreated.
`participant.identity`string	Who accepted.
`invitation.id`string	The invitation this answers.

stage_invitation_accepted.json

{
  "event": "stage_invitation_accepted",
  "room": { "name": "114", "sid": "RM_Lfzv9uoLpyMs" },
  "participant": { "identity": "48" },
  "invitation": { "id": "inv_3f2a…" }
}

stage_invitation_declined

The invited participant declines.

الحقل	المعنى
`room.name`string	Your room id, exactly as you created it.
`room.sid`string	The media server's own room id. Changes if the room is recreated.
`participant.identity`string	Who declined.
`invitation.id`string	The invitation this answers.

stage_invitation_declined.json

{
  "event": "stage_invitation_declined",
  "room": { "name": "114", "sid": "RM_Lfzv9uoLpyMs" },
  "participant": { "identity": "48" },
  "invitation": { "id": "inv_3f2a…" }
}

participant_role_changed

A room owner or admin changes someone's role.

الحقل	المعنى
`room.name`string	Your room id, exactly as you created it.
`room.sid`string	The media server's own room id. Changes if the room is recreated.
`participant.identity`string	Whose role changed.
`role.previous`string	Role before the change.
`role.current`string	Role after the change.
`role.changed_by`string	Who made the change.
`role.reason`string	Why. `owner` means an authorised person did it deliberately.

participant_role_changed.json

{
  "event": "participant_role_changed",
  "room": { "name": "114", "sid": "RM_Lfzv9uoLpyMs" },
  "participant": { "identity": "48" },
  "role": { "previous": "audience", "current": "admin", "changed_by": "148", "reason": "owner" }
}

المقاعد

من قعد، من قام، وأي مقعد اتقفل.

seat_taken

A participant takes a seat, or is placed on one.

الحقل	المعنى
`room.name`string	Your room id, exactly as you created it.
`room.sid`string	The media server's own room id. Changes if the room is recreated.
`participant.identity`string	Who is on the seat.
`seat.index`number	Zero-based seat position.

seat_taken.json

{
  "event": "seat_taken",
  "room": { "name": "402", "sid": "RM_5QnMVtk5tgAs" },
  "participant": { "identity": "48" },
  "seat": { "index": 3 }
}

seat_left

A seat is vacated.

الحقل	المعنى
`room.name`string	Your room id, exactly as you created it.
`room.sid`string	The media server's own room id. Changes if the room is recreated.
`participant.identity`string	Who left the seat.
`seat.index`number	The seat that is now free.

seat_left.json

{
  "event": "seat_left",
  "room": { "name": "402", "sid": "RM_5QnMVtk5tgAs" },
  "participant": { "identity": "48" },
  "seat": { "index": 3 }
}

seat_locked

A host locks a seat so nobody can take it.

الحقل	المعنى
`room.name`string	Your room id, exactly as you created it.
`room.sid`string	The media server's own room id. Changes if the room is recreated.
`seat.index`number	The locked seat.
`seat.locked_by`string	Who locked it.

seat_locked.json

{
  "event": "seat_locked",
  "room": { "name": "402", "sid": "RM_5QnMVtk5tgAs" },
  "seat": { "index": 3, "locked_by": "148" }
}

seat_unlocked

A host unlocks a seat.

الحقل	المعنى
`room.name`string	Your room id, exactly as you created it.
`room.sid`string	The media server's own room id. Changes if the room is recreated.
`seat.index`number	The unlocked seat.
`seat.unlocked_by`string	Who unlocked it.

seat_unlocked.json

{
  "event": "seat_unlocked",
  "room": { "name": "402", "sid": "RM_5QnMVtk5tgAs" },
  "seat": { "index": 3, "unlocked_by": "148" }
}

البث المباشر

نهاية البث وسببها.

live_ended

A live broadcast ends. `reason` says why — `host_left` means the host disconnected rather than closing it.

الحقل	المعنى
`room.name`string	Your room id, exactly as you created it.
`room.sid`string	The media server's own room id. Changes if the room is recreated.
`participant.identity`string	The host the broadcast belonged to.
`participant.reason`string	Why it ended. `host_left` when the host's connection dropped.

live_ended.json

{
  "event": "live_ended",
  "room": { "name": "114", "sid": "RM_Lfzv9uoLpyMs" },
  "participant": { "identity": "148", "reason": "host_left" }
}

معارك PK

بداية المعركة ونهايتها. تحديثات النقاط لحظية بلا ويب‌هوك — النتيجة المعتمدة بتيجي مع pk_ended.

pk_started

A PK battle begins. Score updates are realtime only — there is no webhook per point; the settled tally arrives with pk_ended.

الحقل	المعنى
`battle.battle_id`string	Battle id. Use it to correlate with pk_ended.
`battle.status`string	`active` while it runs.
`battle.room_a / room_b`string	The two room ids. There is no `side_a` / `team_1` / `a` — the sides are a and b, spelled as these fields.
`battle.host_a / host_b`string	Each side's host identity. Never null.
`battle.host_a_name / host_b_name`string \| null	Display name, or null when unknown — never the identity substituted in.
`battle.host_a_avatar / host_b_avatar`string \| null	Avatar url, or null.
`battle.score_a / score_b`number	Points per side. 0 at the start.
`battle.top_a / top_b`array	Top three supporters per side, highest first. Always an array — [] when nobody has sent a gift, never null.
`battle.duration_seconds`number	Planned length.
`battle.winner`string \| null	null while active.
`battle.end_reason`string \| null	null while active.
`battle.started_at / ends_at / ended_at`string \| null	ISO-8601 UTC. ended_at is null while active.
`battle.metadata`object \| null	Whatever you attached when creating the battle.

pk_started.json

{
  "event": "pk_started",
  "battle": {
    "battle_id": "pk_70b45421a5b7380d5b35e9a6",
    "status": "active",
    "room_a": "91",
    "host_a": "46",
    "host_a_name": "UP TO DATE",
    "host_a_avatar": null,
    "room_b": "42",
    "host_b": "48",
    "host_b_name": "RECHIL STERK",
    "host_b_avatar": null,
    "score_a": 0,
    "score_b": 0,
    "top_a": [],
    "top_b": [],
    "duration_seconds": 300,
    "winner": null,
    "end_reason": null,
    "started_at": "2026-09-22T18:35:53.000Z",
    "ends_at": "2026-09-22T18:40:53.000Z",
    "ended_at": null,
    "metadata": null
  }
}

pk_ended

The battle finishes. Same shape as pk_started, with the settled result filled in.

الحقل	المعنى
`battle.status`string	No longer `active`.
`battle.winner`string \| null	The winning side, or null on a draw.
`battle.end_reason`string	Why it ended — e.g. `ended_by_host`, `host_left`.
`battle.ended_at`string	ISO-8601 UTC.
`battle.score_a / score_b`number	Final tally. This is the authoritative result.

pk_ended.json

{
  "event": "pk_ended",
  "battle": {
    "battle_id": "pk_a6dae4bb78791c0803f4724c",
    "status": "ended",
    "room_a": "91",
    "host_a": "46",
    "room_b": "42",
    "host_b": "48",
    "score_a": 0,
    "score_b": 0,
    "top_a": [],
    "top_b": [],
    "winner": null,
    "end_reason": "ended_by_host",
    "ended_at": "2026-09-22T18:35:46.000Z"
  }
}

pk_invited

One host invites another to a battle, before it starts.

الحقل	المعنى
`battle`object	Same battle object as pk_started, with status not yet active.

pk_invited.json

{
  "event": "pk_invited",
  "battle": { "battle_id": "pk_70b4…", "status": "pending", "room_a": "91", "room_b": "42" }
}

شكل الداعم في top_a و top_b

كل عنصر بيحمل المفردتين — الجديدة والقديمة — بنفس القيمة. الاسم والأفاتار بيبقوا null لما يكونوا مجهولين، والمعرّف عمره ما بيتحط مكان الاسم.

contributor.json

{
  "user_id": "48",
  "identity": "48",
  "user_name": "RECHIL STERK",
  "name": "RECHIL STERK",
  "user_avatar": null,
  "avatar_url": null,
  "points": 1200,
  "rank": 1
}

جاهز تبني مع UTD؟

أنشئ حسابك، اشحن محفظتك الأم، وشغّل الخدمات التي تحتاجها.

أنشئ حسابك المجاني