الويب هوك الصادر: إشعارات فورية لنظامك

ما هو الويب هوك الصادر؟#

بدل أن يسأل نظامك المنصة كل دقيقة «هل تغيّر شيء؟»، تُرسل المنصة نفسها طلب POST بجسم JSON إلى رابط HTTPS تحدده أنت حالما يقع حدث، مثل تسليم طرد. كل رسالة موقّعة وتُعاد محاولتها عند الفشل (راجع مقالتي التحقق من التوقيع وإعادة المحاولة).

من يستطيع استخدامه#

• التاجر (تاجر منصة): من لوحة التاجر أو من الـ API. أما التاجر الذي أنشأته شركة توصيل فلا يستطيع استخدامه: يتلقى 403 api_not_allowed في الـ API، وتعيد اللوحة توجيهه مع تنبيه.
• مدير شركة التوصيل: من لوحة الشركة فقط (لا يوجد API للويب هوك في واجهة الشركة). تتلقى الشركة أحداث طرودها وحدها.
• الباقة (حين تنطبق الباقات على حسابك): يلزم تفعيل ميزة «الويب هوك» في الباقة لإضافة رابط جديد (وإلا 403 plan_feature في الـ API، ورسالة الباقة في اللوحة)، ويحتاج مسار الـ API أيضاً إلى ميزة api. وعدد الروابط هو الأقل بين 10 وقيمة «عدد روابط الويب هوك» في الباقة (الافتراضي في نموذج الباقة الجديدة 3 للتجار و5 للشركات، والقيمة الفارغة أو 0 تعني السقف 10 فقط).

شروط الرابط#

• يبدأ بـ https:// حصراً ولا يزيد على 500 حرف؛ لأن الرسائل تحمل بيانات الزبائن.
• بلا اسم مستخدم وكلمة مرور داخل الرابط (user:pass@)، وبلا منفذ غير 443 أو 8443.
• يجب أن يُحَلّ اسم النطاق عبر DNS، وأن تكون كل عناوينه (IPv4 و IPv6) عامة: تُرفض العناوين الخاصة والمحجوزة وعناوين الحلقة المحلية (loopback) وعناوين الارتباط المحلي (link-local) وعناوين CGNAT (100.64.0.0/10). يُعاد هذا الفحص عند كل إرسال.
• لا تُتَّبع إعادة التوجيه (3xx تُعدّ فشلاً)، ويجب الرد بـ 2xx خلال 10 ثوانٍ.

تسجيل رابط#

1. افتح صفحة الويب هوك

   التاجر: من «الويب هوك والـ API» افتح بطاقة «إشعارات لنظامك (Webhook صادر)» واضغط «إدارة الويب هوك». مدير الشركة: من «الربط والـ API» اضغط «الويب هوك» أو «إدارة الروابط والسجل».

2. أضف رابطاً

   افتح «رابط جديد» وأدخل «رابط الاستقبال»، واكتب اسماً اختيارياً في «اسم (اختياري)»، ثم علّم الأحداث المطلوبة أو «كل الأحداث». يأتي حدث «تغيّر حالة الطرد» معلَّماً مسبقاً. أبقِ «مفعّل» معلَّماً واضغط «إضافة».

3. انسخ مفتاح التوقيع

   بعد الإضافة يعرض «مفتاح التوقيع» كاملاً، ثم يظهر مقنَّعاً مع أيقونات إظهار ونسخ وتجديد. التجديد يُبطل المفتاح القديم فوراً.

4. جرّب بـ «إرسال تجربة»

   تُرسل المنصة رسالة ping موقّعة إلى رابطك وتُظهر رد نظامك (رمز HTTP) أو سبب الفشل.

5. أو سجّل الرابط عبر الـ API (للتاجر)

   أرسل POST /api/v1/webhooks بمفتاح الـ API. يعيد الرد 201 مع الحقل secret مرة واحدة فقط.

1234

1. مفاتيح الـ API الحالية (تُعرض مخفية)
2. اسم المنصة أو النظام الذي ستربطه
3. أنشئ مفتاحاً جديداً
4. افتح توثيق الـ API

curl -X POST https://YOUR_PLATFORM_DOMAIN/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Warehouse system","url":"https://example.com/webhooks/delivery-syria","events":["parcel.delivered","parcel.returned"]}'

للإدارة أيضاً: GET /api/v1/webhooks وPATCH وDELETE على /api/v1/webhooks/{id} وPOST /api/v1/webhooks/{id}/test، وGET /api/v1/webhooks/events. في الـ API تختار * أو أسماء أحداث دقيقة (نمط مثل parcel.* يعطي 422 validation_failed). سجل الرسائل وإعادة الإرسال متاحان في اللوحة فقط.

الأحداث#

عشرة أحداث، إضافة إلى ping:

• قد يُرسل تغيّر واحد في حالة الطرد رسالتين: parcel.status_changed وحدث المرحلة (مثل parcel.delivered)، ولكل منهما X-DS-Event-Id خاص. والطرد الجديد يرسل عادةً parcel.created ثم parcel.status_changed (الحالة 5)؛ وطرد awaiting_funds الذي يُموَّل لاحقاً يرسل parcel.status_changed لا parcel.created.
• نماذج الموظفين المخصصة للاستلام والفروع (إسناد الاستلام أو إعادة جدولته، واستلام مندوب الاستلام للطرد، والتحويل إلى فرع أو الاستلام فيه) ونماذج التراجع عن خطوات الاستلام والمستودع والفروع والتوصيل (التراجع عن إسناد الاستلام، وإعادة جدولة الاستلام، واستلام مندوب الاستلام للطرد، والاستلام في المستودع، والتحويل إلى فرع، والاستلام في الفرع، وإسناد التوصيل، وإعادة جدولة التوصيل) لا ترسل أي ويب هوك. أما التراجع عن التسليم الكامل أو الجزئي وعن خطوات الإرجاع فيرسل parcel.status_changed. والحالة التي تُضبط عبر مسار تغيير الحالة العام (واجهة الـ API لتطبيق الموظفين على الجوال، ومسار تغيير الحالة العام، ومزامنة شركة الشحن الخارجية) ترسل parcel.status_changed أيضاً. اقرأ الطرد بـ GET /parcels/{tracking} حين تحتاج حالته الحالية.
• أحداث wallet.* للتجار فقط. وتتلقى الشركة أحداث parcel.* الثمانية لطرود شركتها، ويضيف جسم الرسالة merchant وdeliveryman.

شكل الرسالة#

POST بالترويستين Content-Type: application/json وUser-Agent: DeliverySyria-Webhook/2.0، مع هذه الترويسات:

{
  "id": "evt_xxxxxxxxxxxxxxxxxxxxxxxx",
  "event": "parcel.delivered",
  "created_at": "2026-10-14T14:32:05+00:00",
  "data": {
    "id": 1043,
    "tracking_number": "DS261013AB12CD",
    "reference": "ORDER-1043",
    "stage": "delivered",
    "status_code": 9,
    "recipient": { "name": "Example Name", "phone": "0900000000" },
    "cod_amount": 50.0,
    "cod_collected": 50.0,
    "tracking_url": "https://YOUR_PLATFORM_DOMAIN/t/DS261013AB12CD"
  }
}

• data في أحداث الطرد هو كائن الطرد نفسه في الـ API (مختصر في المثال). أما wallet.* فتحمل id وamount وcurrency (دائماً USD) وrecharge_balance مع حقول تختلف حسب الحدث.
• status_label (في كائن الطرد الكامل) نص محلّي، فاعتمد على status_code وstage. وتاريخ created_at بالتوقيت العالمي UTC (+00:00).

أخطاء شائعة#

• نظامك بطيء أو يعيد التوجيه (مثل التحويل من www.example.com إلى example.com): يُحتسب فشلاً. أعِد 2xx فوراً وعالج في الخلفية.
• افتراض وصول الرسالة مرة واحدة وبالترتيب: قد تتكرر الرسالة أو تتأخر؛ تجاهل ما عالجته بحسب X-DS-Event-Id.
• الرابط الموقوف لا يستقبل شيئاً: لا تُخزَّن الأحداث أثناء الإيقاف (راجع مقالة إعادة المحاولة).

الصلاحيات والحدود#

• في اللوحة: إضافة رابط وتجربته وإعادة إرسال رسالة محدودة بـ 20 و10 و30 في الدقيقة على الترتيب (حدود الـ API في مقالة حدود الطلبات).
• إذا خلت الباقة من ميزة الويب هوك فلا تُرسل المنصة أحداثاً؛ أما انتهاء الاشتراك وحده فلا يوقف الإرسال.