الانتقال إلى المحتوى الرئيسي

الإعداد

يدعم IDCloud نمطين للـ webhook، يعتمدان على طريقة تكاملك:

  • عبر البوابة الإلكترونية — لتكاملات الويب وSDK. تهيئة ذاتية مباشرة في بوابة IDCloud.
  • حسب العميل — لتكاملات API التي تستخدم إمكانية تنسيق Check (تدفق غير متزامن). يتم تهيئتها بواسطة فريق Unico. متاح في البرازيل فقط.

لتسجيل نقطة نهاية الـ 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

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

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

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

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

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

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

آخر تحديث في