Webhooks / الأحداث

الأحداث

يرسل صدى حدث JSON موقّعاً بـ POST إلى مسارك عند بدء المكالمة وانضمام المشاركين ومغادرتهم وانتهائها أو فواتها. كل تسليم بالغلاف نفسه.

حُدّث في 21 أكتوبر 2026 عدّل هذه الصفحة

01الغلاف

كل حدث كائن JSON يحمل معرّفاً واسم الحدث والبيئة وطابعاً زمنياً وكائن data يصف المكالمة. هذا تسليم كامل بترويساته.

POST /webhooks/sada

1 POST /webhooks/sada HTTP/1.1

2 Host: api.example.iq

3 Content-Type: application/json

4 User-Agent: Sada-Webhooks/1.0

5 X-Sada-Event: call.ended

6 X-Sada-Signature: t=1792316400,v1=3f786850e387550fdab836ed7e6dc881de23001b4a9d1a5d2a1f8f3c7a0b9e2d

8 {

9 "id": "evt_9k2m4p7q1s8d3f6h",

10 "event": "call.ended",

11 "env": "test",

12 "created_at": "2026-10-21T09:40:00+00:00",

13 "data": {

14 "call_id": "call_k3j9x2m7qa",

15 "type": "one_to_one",

16 "status": "completed",

17 "region": "baghdad",

18 "ring": true,

19 "metadata": { "order_id": "ord_42" },

20 "started_at": "2026-10-21T09:30:00+00:00",

21 "connected_at": "2026-10-21T09:30:04+00:00",

22 "ended_at": "2026-10-21T09:40:00+00:00",

23 "duration_seconds": 600,

24 "participant_minutes": 20

25 }

26 }

02الأحداث

الأحداث الخمسة التي تستطيع الاشتراك فيها، مع نبضة الاختبار.

الحدث	متى يُرسل
`call.started`	أُنشئت المكالمة (`POST /calls`). الحالة `ringing` أو `in_progress`.
`participant.joined`	أُصدر رمز انضمام لمشارك. `data.participant` يصفه.
`participant.left`	غادر مشارك المكالمة. `data.participant.left_at` مضبوط.
`call.ended`	انتهت المكالمة بعد أن اتصلت. `duration_seconds` و`participant_minutes` نهائيان.
`call.missed`	انتهت المكالمة قبل أن تتصل — لم يُجب أحد. `participant_minutes` يساوي 0.
`test.ping`	يرسله زر «إرسال اختبار» في لوحة التحكم؛ `data` هي `{ "test": true }`.

03كائن البيانات

لأحداث المكالمة، data هي المكالمة لحظة الحدث.

الحقل	المعنى
`id`	معرّف فريد للحدث، `evt_…`. استخدمه لإسقاط التكرارات.
`event`	اسم الحدث.
`env`	`test` أو `live` — بيئة المفتاح الذي أنشأ المكالمة.
`created_at`	وقت إنتاج الحدث، ISO 8601.
`data.call_id`	المكالمة.
`data.type`	`one_to_one` أو `group`.
`data.status`	الحالة لحظة الحدث.
`data.region`	المنطقة التي مرّ عبرها الصوت.
`data.ring`	هل أُنشئت المكالمة بالرنين.
`data.metadata`	الـ `metadata` الخاصة بك كما هي.
`data.started_at`	وقت الإنشاء.
`data.connected_at`	حين حصل المشارك الثاني على رمز؛ `null` قبل ذلك.
`data.ended_at`	`null` ما دامت المكالمة حيّة.
`data.duration_seconds`	الثواني من `started_at` إلى `ended_at` (أو الآن).
`data.participant_minutes`	الدقائق المفوترة؛ نهائية في `call.ended` و0 قبلها.

04أحداث المشاركين

participant.joined وparticipant.left يضيفان كائن participant إلى data يحمل user_ref الخاص بك والاسم الظاهر وأوقات الانضمام والمغادرة.

participant.joined

1 {

2 "id": "evt_2c8v5b1n7m4k9j3h",

3 "event": "participant.joined",

4 "env": "test",

5 "created_at": "2026-10-21T09:30:04+00:00",

6 "data": {

7 "call_id": "call_k3j9x2m7qa",

8 "type": "one_to_one",

9 "status": "in_progress",

10 "…": "…",

11 "participant": {

12 "user_ref": "u_1842",

13 "display_name": "محمود عباس",

14 "joined_at": "2026-10-21T09:30:04+00:00",

15 "left_at": null

16 }

17 }

18 }

05الترويسات

كل تسليم يحمل هذه الترويسات.

الترويسة	القيمة
`Content-Type`	`application/json`، بترميز UTF-8 والعربية غير مهرّبة.
`X-Sada-Event`	اسم الحدث، لتوجّهه قبل تحليل الجسم.
`X-Sada-Signature`	`t=<unix>,v1=<hex>` — راجع التحقق من التوقيع.
`User-Agent`	`Sada-Webhooks/1.0`.

أضف مساراً HTTPS في لوحة التحكم ← Webhooks، واختر الأحداث التي يستقبلها، وأرسل نبضة اختبار. المسارات لكل تطبيق ولكل بيئة، فالمفتاح التجريبي لا يصل إلا إلى مسارك التجريبي.

ردّ بأي 2xx خلال 5 ثوانٍ — ونفّذ عملك بعد الرد، في طابور. أي شيء آخر يُعاد إرساله؛ راجع إعادة المحاولة.

test.ping

1 {

2 "id": "evt_7h2k9m4p1q8s3d6f",

3 "event": "test.ping",

4 "env": "test",

5 "created_at": "2026-10-21T09:00:00+00:00",

6 "data": { "test": true }

7 }

✓ شكراً، وصلتنا ملاحظتك.