الإعداد

لتسجيل نقطة نهاية الـ webhook الخاصة بك أو تحديثها، ادخل إلى بوابة IDCloud وانتقل إلى الإعدادات > Webhook.

المعلومات المطلوبة

الحقل	الوصف
رابط الإشعار	نقطة النهاية التي ستتصل بها Unico لإرسال إشعارات الأحداث. يجب أن تكون قابلة للوصول عبر HTTPS.
نوع المصادقة	كيف تصادق Unico على نقطة النهاية الخاصة بك. انظر الخيارات أدناه.
إعدادات إعادة المحاولة	الحد الأقصى لعدد المحاولات والفترة الفاصلة بينها (يتم تطبيق التراجع الأسي).
حد التزامن	الحد الأقصى لعدد عمليات التسليم المتزامنة قيد التنفيذ (الحد الأقصى: 500).
المهلة الزمنية	الحد الأقصى لوقت الانتظار لرد نقطة النهاية، بالثواني.
الحالات المراد إشعارها	مجموعة حالات العملية التي تُطلق إشعاراً. مثبّتة حالياً على `PROCESS_STATE_FINISHED`؛ غير قابلة للتهيئة في الوقت الحالي.

طرق المصادقة

OAuth2

قدّم:

endpoint الـ Webhook
URL مزود OAuth2
ClientId مزود OAuth2
Secret مزود OAuth2

ستطلب Unico رمز وصول من URL المزود باستخدام بيانات اعتماد العميل وستمرره إلى نقطة النهاية الخاصة بك كرمز Bearer.

Basic Authorization

قدّم بيانات الاعتماد بتنسيق user:pass. تقوم Unico بترميزها بـ Base64 وإرسالها في رأس الطلب Authorization: Basic <encoded> في كل استدعاء للـ webhook.

API Key

يُدعم تنسيقان. يتم تقسيم السلسلة عند أول نقطتين:

header:value — يُحدد اسم رأس طلب مخصصاً. أمثلة:
- X-API-Key:abc123 → X-API-Key: abc123
- Authorization:Bearer abc123 → Authorization: Bearer abc123
value فقط (بدون نقطتين) — تُرسل القيمة في رأس الطلب Authorization بدون بادئة نظام مصادقة. مثال: abc123 → Authorization: abc123.

استخدم تنسيق header:value عند الحاجة إلى نظام Bearer (مثل: Authorization:Bearer <token>)؛ أما تنسيق القيمة فقط فيُرسل القيمة الخام بدون بادئة.

بدون مصادقة

لا يتم إرسال بيانات اعتماد. يُوصى بهذا فقط لبيئات التطوير — يجب أن تتطلب نقاط النهاية في الإنتاج دائماً مصادقة.

حالات العملية التي تُطلق الإشعارات

حالياً، ترسل Unico إشعاراً في كل مرة تنتقل فيها عملية إلى:

الحالة	الوصف
`PROCESS_STATE_FINISHED`	انتهت العملية — حالة نهائية، بغض النظر عن النتيجة.

قد تتطور الحالات

قد تتغير مجموعة الحالات التي تُرسل إشعاراً بها المنصة في المستقبل. اجعل الحالات التي تستجيب لها نقطة النهاية قابلة للتهيئة، بحيث لا يتطلب إضافة حالة جديدة إعادة نشر خدمتك.

تنسيق الطلب

عمليات تسليم الـ webhook هي طلبات POST إلى نقطة النهاية الخاصة بك. يحتوي الجسم على معرّف العملية والحالة الحالية.

{
  "processId": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "state": "PROCESS_STATE_FINISHED",
  "flow": "id"
}

lastEvent وlastEventDescription

يظهر هذان الحقلان في الحمولة فقط عندما تنتهي صلاحية العملية قبل إكمال المستخدم للرحلة. ولا يوجدان في حمولات الإتمام الطبيعية. راجع أنواع الأحداث للاطلاع على المخطط الكامل وقائمة قيم lastEvent المحتملة.

الرد المتوقع

يجب أن تستجيب نقطة النهاية بشكل متزامن:

نجاح: أي حالة HTTP في نطاق 200–299.
فشل: أي حالة أخرى. ستعيد Unico المحاولة بتراجع أسي حتى الحد الأقصى المهيّأ لعدد المحاولات، أو حتى استلام 2xx.

استجب بسرعة

اعترف بالـ webhook بسرعة (قبل انتهاء المهلة المهيّأة) وعالج الحمولة بشكل غير متزامن من طرفك. المعالجة الطويلة داخل معالج الـ webhook تزيد من احتمال انتهاء المهلة وإعادة المحاولات غير الضرورية.

للاطلاع على إرشادات الأمانة (Idempotency) ومعالجة إعادة المحاولة، راجع الأمان.

المعلومات المطلوبة​

طرق المصادقة​

حالات العملية التي تُطلق الإشعارات​

تنسيق الطلب​

الرد المتوقع​

المعلومات المطلوبة

طرق المصادقة

حالات العملية التي تُطلق الإشعارات

تنسيق الطلب

الرد المتوقع