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

كل حدث ويب هوك، وموعد إطلاقه، والحمولة الدقيقة التي يرسلها.

للمستخدمين المتقدمين

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

غلاف الحدث

كل تسليم ويب هوك هو طلب HTTP بنوع POST وجسم JSON. تشترك جميع الأحداث في نفس الغلاف العلوي:

الحقل	النوع	الوصف
`id`	نص	معرّف فريد للحدث، يبدأ بـ`evt_` (32 حرفًا سداسيًا عشريًا). استخدمه كمفتاح عدم تكرار — قد يُسلَّم الحدث نفسه أكثر من مرة
`type`	نص	اسم الحدث، مثل `order.approved`
`apiVersion`	نص	إصدار الحمولة المؤرَّخ. حاليًا `2026-07-01`
`createdAt`	نص	وقت حدوث الحدث (بصيغة ISO 8601)
`account.uid`	نص	معرّف الحساب (المالك) الذي ينتمي إليه الحدث
`account.companyName`	نص	اسم شركتك، إن وُجد
`data`	كائن	لقطة للمورد الذي يتعلق به الحدث (راجع أقسام كل حدث أدناه)
`changes`	كائن	فقط في بعض الأحداث — لقطتا `previous` و`current` للحقول التي تغيّرت

{
  "id": "evt_9f2c4b7a1d3e5f60718293a4b5c6d7e8",   // مفتاح عدم التكرار
  "type": "order.approved",                        // اسم الحدث
  "apiVersion": "2026-07-01",
  "createdAt": "2026-07-28T14:30:00.000Z",
  "account": {
    "uid": "abc123",
    "companyName": "Acme Home Services"
  },
  "data": { /* لقطة المورد — راجع أدناه */ },
  "changes": {                                     // فقط في *.approved، و*.completed،
    "previous": { "status": "new" },               // *.status_changed، و*.rescheduled
    "current": { "status": "approved" }
  }
}

يحمل كل تسليم أيضًا اسم الحدث في ترويسة الطلب webhook-event، إلى جانب ترويسات التوقيع (webhook-id، وwebhook-timestamp، وwebhook-signature) الموصوفة في دليل الويب هوكس.

فهرس الأحداث

الحدث	يُطلَق عندما	حقل `changes`
`order.created`	يُنشأ Order جديد — من لوحة التحكم، أو تطبيق الموبايل، أو صفحة الجدولة عبر الإنترنت	—
`order.approved`	تصبح حالة Order معتمد (بما في ذلك ما يُنشأ معتمدًا)	`status`
`order.completed`	تصبح حالة Order مكتمل	`status`
`order.rescheduled`	يتغيّر تاريخ/وقت الموعد على Order معتمد	`appointmentDateTime`
`order.status_changed`	يُطلَق مع `order.approved` و`order.completed`، وأيضًا عندما ينتقل Order معتمد إلى حالة سابقة	`status`
`invoice.paid`	يُعلَّم Order كمدفوع (تصبح علامة `paid` فيه `true` لأول مرة)	—
`report.published`	يصبح Order لأول مرة مدفوعًا وموقَّع الاتفاقية معًا — اللحظة التي يُطلَق فيها Report الخاص به	—

قيم الحالة في الحمولات هي القيم المخزَّنة الخام (draft، new، read، approved، complete، archived) — راجع حالات الطلبات.

أسماء الحقول لا تتغير حسب المجال

أسماء حقول الحمولة متطابقة عبر جميع المجالات. مثلًا، تُرسل Inspection Type دائمًا في حقل باسم inspectionType، بغض النظر عن الاسم الذي يستخدمه مجالك على الشاشة.

أحداث الطلبات — حمولة `data`

order.created، وorder.approved، وorder.completed، وorder.rescheduled، وorder.status_changed ترسل جميعها نفس لقطة Order في data:

{
  "id": "req_abc123",                              // معرّف الطلب
  "status": "approved",                            // راجع مرجع حالات الطلبات
  "appointmentDateTime": "2026-08-01T13:00:00.000Z",
  "inspectionType": "Buyer Inspection",            // اسم فئة الخدمة عندك
  "streetAddress": "123 Main St",
  "city": "Springfield",
  "region": "IL",
  "postalCode": "62701",
  "country": "US",
  "timezone": "America/Chicago",
  "contactName": "Jane Buyer",
  "contactEmail": "jane@example.com",
  "contactPhone": "(555) 123-4567",
  "contactType": "client",
  "totalPrice": 450,
  "totalTime": 120,                                // المدة بالدقائق
  "paid": false,
  "agreementSigned": true,
  "assignedInspectors": ["uid1", "uid2"],          // معرّفات أعضاء الفريق المعيَّنين
  "requestDateTime": "2026-07-20T09:15:00.000Z",   // وقت إنشاء الطلب
  "approvedDateTime": "2026-07-21T10:00:00.000Z",
  "completedDateTime": "2026-08-01T16:30:00.000Z"
}

حقول التاريخ هي نصوص بصيغة ISO 8601. أي حقل بلا قيمة يُحذف من الحمولة بدلًا من إرساله كـnull.

`changes` لكل حدث طلب

order.approved — changes.previous.status / changes.current.status (القيمة الحالية دائمًا "approved")
order.completed — changes.previous.status / changes.current.status (القيمة الحالية دائمًا "complete")
order.status_changed — changes.previous.status / changes.current.status
order.rescheduled — changes.previous.appointmentDateTime / changes.current.appointmentDateTime (نصوص ISO 8601)
order.created — لا يوجد حقل changes

الاعتماد يُطلق حدثين

اعتماد Order يُرسل كلًا من order.approved وorder.status_changed؛ وإكماله يُرسل كلًا من order.completed وorder.status_changed. اشترك في أحدهما فقط إلا إذا كنت تريد كلا التسليمين.

يُطلَق أول مرة تصبح فيها علامة paid لـOrder هي true. حمولة data هي نفس لقطة Order المعروضة أعلاه — ليست كائن فاتورة. لا توجد حقول خاصة بالفاتورة (لا رقم فاتورة، ولا مبلغ مدفوع، ولا طريقة دفع)؛ استخدم totalPrice وعلامة paid: true، أو استرجع تفاصيل الفاتورة من الـ API. لا يُرسل حقل changes.

`report.published` — حمولة `data`

يُطلَق عندما يصبح Order لأول مرة مدفوعًا وموقَّع الاتفاقية معًا — اللحظة التي يُطلَق فيها Report المنشور للعميل. حمولة data هي لقطة Order المعروضة أعلاه، بالإضافة إلى حقل واحد إضافي:

{
  "orderId": "req_abc123",   // نفس data.id — الطلب الذي ينتمي إليه هذا التقرير
  "id": "req_abc123",
  "status": "complete"
  // …بقية حقول لقطة الطلب
}

لا يُرسل حقل changes. لا تتضمن الحمولة روابط التقرير.

أحداث يمكنك الاشتراك فيها لكنها لا تُرسل بعد

يسرد محرر نقطة النهاية أيضًا order.updated، وinvoice.created، وcontact.created، وcontact.updated. أسماء هذه الأحداث محجوزة ويمكن اختيارها، لكن لا يوجد نشاط حالي في الحساب يولّدها — نقاط النهاية المشتركة فقط في هذه الأحداث لن تستقبل أي تسليمات. إذا أُطلقت في المستقبل، ستستخدم الغلاف القياسي؛ حقول data الخاصة بها غير محدَّدة بعد.

أحداث الاختبار — `webhook.test`

النقر على اختبار على نقطة نهاية يرسل حدث webhook.test:

{
  "id": "evt_test_5f0e…",        // يبدأ بـevt_test_
  "type": "webhook.test",
  "apiVersion": "2026-07-01",
  "createdAt": "2026-07-28T14:30:00.000Z",
  "account": { "uid": "abc123" },
  "data": {
    "message": "This is a test webhook event.",
    "timestamp": "2026-07-28T14:30:00.000Z"
  }
}

أحداث الاختبار غير موقَّعة — تحمل ترويسة X-Webhook-Test: true بدلًا من ترويسات التوقيع. يجب أن يقبلها المستقبِل دون التحقق من التوقيع (أو أن يتعرّف على الترويسة ويتجاوز التحقق للاختبارات فقط).

الاستجابة للتسليمات

استجب بأي حالة 2xx خلال 10 ثوانٍ لتأكيد استلام التسليم.
استجابات 5xx وانتهاء المهلة تُعامَل كمؤقتة — تُعاد محاولة التسليم.
استجابات 4xx الأخرى تُعامَل كنهائية — لا تُعاد محاولة ذلك التسليم.
الاستجابة بـ410 Gone تُخبر ITB بالتوقف عن الإرسال: تُعطَّل نقطة النهاية فورًا.

حدود نقاط النهاية، والتعطيل التلقائي بعد فشل متكرر، وسجل التسليم، والتحقق من التوقيع، كل ذلك موضّح في دليل الويب هوكس.