Webhook

تصف مقالات GetProcess في هذه الوثائق طريقة للحصول على حالة العملية من خلال استدعاء نقطة نهاية (endpoint). بهذه الطريقة، يتم إجراء استقصاء دوري (polling) لتلقي معلومات حول العمليات التي تم إنشاؤها. هذا يعني أنه يمكن استدعاء نقطة النهاية عدة مرات لنفس العملية للحصول على أحدث حالة.

باستخدام آليات Webhook، يمكن إشعار نقطة نهاية محددة في كل مرة تتغير فيها حالة العملية.

ما هو الـ Webhook؟

الـ Webhook هو خدمة إشعارات نظامية تتيح التكامل غير المتزامن (asynchronous) بين الأنظمة، حيث يقوم أحد الأنظمة بإشعار الآخر عبر مُحفِّز (trigger). بهذه الطريقة، يمكن لآليات Webhook إبقاء الأنظمة محدَّثة بأحدث المعلومات دون الحاجة إلى استقصاء دوري (polling) مستمر للتحقق من التحديثات.

كيفية إعداد الـ Webhook

لإعداد الـ Webhook، يلزم توفير المعلومات التالية:

• رابط الإشعار (Notification URL): هذه هي نقطة النهاية التي يستخدمها Unico لإرسال الإشعارات المتعلقة بتحديثات الحالة.
• نوع المصادقة (Authentication Type): هذه هي الطريقة المستخدمة لمصادقة استدعاء نقطة النهاية. الخيارات التالية متاحة:
  • OAuth2؛
  • Basic Authorization؛
  • API Key؛
  • بدون مصادقة.
• بالنسبة لـ OAuth2، يلزم توفير المعلومات التالية:
  • endpoint الخاص بـ Webhook؛
  • URL الخاص بمزود OAuth2؛
  • ClientId الخاص بمزود OAuth2؛
  • Secret الخاص بمزود OAuth2.
• بالنسبة لـ Basic Authorization، يلزم الإرسال بالتنسيق user:pass.
• بالنسبة لـ API Key، يوجد تنسيقان ممكنان:
  • header:value، عندما يكون اسم رأس (header) محدد مطلوبًا؛
  • value، عندما يكون الرأس المطلوب هو Authorization.
• إعدادات إعادة المحاولة (Retry Settings): يشير هذا إلى عدد المحاولات في حال حدوث فشل عند استدعاء نقطة النهاية:
  • الحد الأقصى لعدد المحاولات؛
  • الفاصل الزمني بين المحاولات (بالثواني)؛
  • حد المعدل (Rate Limit): الحد الأقصى لعدد الإرسالات المتزامنة (الحد الأقصى: 500)؛
  • مهلة الانتظار (Timeout): الحد الأقصى لوقت انتظار استجابة نقطة النهاية (بالثواني).
• الحالات التي سيتم الإشعار بها: يمكنك الاشتراك في حالات محددة لتلقي الإشعارات. وتشمل هذه:
  • approved: تمت الموافقة على المعاملة؛
  • processing: المعاملة قيد المعالجة؛
  • inconclusive: لم نتمكن من إجراء تحقق قاطع؛
  • shared: تمت مشاركة المعاملة، بانتظار الإرسال؛
  • skipped: تخطى الشخص عملية الالتقاط البيومتري (biometric) ضمن التدفق؛
  • unknown-share: أشار الشخص إلى أنه لا يتعرف على عملية الشراء؛
  • absent-holder: حامل البطاقة غير حاضر لإجراء الالتقاط؛
  • expired: لم يُكمل الشخص عملية الالتقاط خلال الوقت المحدد وانتهت صلاحية المعاملة.

حول المصادقة

يمكن حماية واجهة برمجة التطبيقات (API) بواسطة طريقة مصادقة مثل Basic Authentication أو API Key. يمكن أيضًا تحديد قائمة بعناوين IP المسموح لها بالوصول لمزيد من الحماية.

التكامل مع التحقق من البطاقة غير الحاضرة

عند إعداد Webhook على المنصة، يمكنك تلقي معلومات حول العمليات من خلال إشعارات تُرسل إلى نقطة نهاية في واجهة برمجة التطبيقات (API) التي طورتها لاستقبال هذه التحديثات.

تشمل المعلومات التي ترسلها المنصة إلى واجهة برمجة التطبيقات ما يلي:

• ID: معرّف المعاملة؛
• Status: حالة المعاملة؛
• HasIdentityChanged: ما إذا كان قد حدث تغيير في الهوية ضمن المعاملة (اختياري).

ملاحظة

لاحظ أنه من الممكن اختيار الحالات التي يرغب العميل في تلقي إشعارات بشأنها من خلال إعداد الـ Webhook. بعد إرسال هذه المعلومات، يجب أن تكون الاستجابة المتوقعة متزامنة (synchronous).

الطلبات

يجب أن يكون الطلب بطريقة POST إلى واجهة برمجة تطبيقات REST، مما يجعل إرسال المعلومات أسهل وأكثر أمانًا. يجب أن تكون جميع الحقول إلزامية. يجب أن يقبل جسم الطلب معرّف المعاملة وحالتها، كما هو موضح في المثال التالي:

{
  "id": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "status": "approved",
  "hasIdentityChanged": false
}

الاستجابة

يجب أن تكون الاستجابة متزامنة. يجب أن تكون حالة الطلبات الناجحة ضمن النطاق من 200 إلى 299. أي حالة أخرى ستُعتبر فشلاً، وسيقوم التحقق من البطاقة غير الحاضرة بإجراء محاولات إشعار إضافية (مع تأخير تصاعدي (exponential backoff) بينها)، حتى تلقي استجابة من النوع 2xx أو الوصول إلى الحد الأقصى لعدد المحاولات.

حالة الاستجابة

حاليًا، لدينا مجموعة من الحالات، لكن هذه المجموعة قد تتغير في المستقبل. لذلك، يُنصح بجعل الحالات التي يهتم بها العميل لاتخاذ إجراء قابلة للتهيئة (configurable). على سبيل المثال، إذا كانت النية اتخاذ إجراء في كل مرة يكتمل فيها الالتقاط بنجاح، فإن هذا يحدث حاليًا مع الحالة "processing". ومع ذلك، بما أن هذا قد يتغير في المستقبل، يُنصح بجعل الحالة التي تشير إلى نجاح الالتقاط قابلة للتهيئة في النظام، بحيث يمكن تنفيذ أي تغيير مستقبلي إلى الحالة "captured" بسهولة.

بالإضافة إلى ذلك، نوصي بأن تكون هناك إجراءات محددة للحالات المحددة وإجراء عام في حال عدم التعرف على الحالة (على سبيل المثال، افتراض أن أي حالة مختلفة عن "processing" و"approved" تُعتبر غير قاطعة). هذا مهم لأن حالات جديدة قد تظهر في المستقبل، ومن غير المتوقع أن يتعطل الـ Webhook بسبب ذلك.

اعتبارات مهمة

انتبه للجوانب التالية عند تطوير واجهة برمجة التطبيقات (API) التي سيستخدمها التحقق من البطاقة غير الحاضرة لإشعارك بتغييرات الحالة:

حد المعدل (Rate limit) — لتجنب الحمل الزائد على مواردك في الحالات التي تحتوي على عدد كبير من المعاملات، من الممكن تحديد حد أقصى لعدد مرات استدعاء نقطة النهاية.

معدل الأخطاء (Error Rate) — يجب أن يظل معدل الأخطاء (الاستجابات خارج النطاق [200, 299]) منخفضًا دائمًا. وإلا، سيتم تقليل إنتاجية الـ Webhook تلقائيًا، وقد يؤدي هذا التقليل، مقترنًا بآلية إعادة المحاولة، إلى زيادة وقت التنفيذ للإشعارات الجديدة.

التكرارية المثالية (Idempotence) — يضمن التنفيذ الحالي للـ Webhook التسليم "مرة واحدة على الأقل" (at-least-once)، لذا قد يتم الإشعار بنفس الحالة أكثر من مرة. لذلك، يجب أن يتم تنفيذ نقطة النهاية بطريقة تحقق مبدأ Idempotence.

الخطة البديلة (Fallback) — في حال حدوث أي تعطل في خدمة الـ Webhook، يُنصح بوجود طريقة بديلة (fallback) لضمان استمرار استرجاع حالات المعاملات ضمن وقت الاستجابة المحدد. تم وصف استعلام نقطة النهاية في قسم مرجع API من هذه الوثائق.