الإعداد

لتهيئة webhook على Unico IDCloud، قدّم نقطة النهاية وطريقة المصادقة وسياسة إعادة المحاولة. يتم التهيئة بواسطة فريق Unico — تواصل مع فريق CS / Onboarding الخاص بك لتسجيل 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": "EVENT_TYPE_PROCESS_CREATED",
  "lastEventDescription": "Process created"
}

للاطلاع على مخطط الحمولة الكاملة وقائمة قيم lastEvent، راجع أنواع الأحداث.

الرد المتوقع

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

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

استجب بسرعة

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

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