Webhook

Webhook هو الطريقة التي يُخبر بها IDCloud نظامك تلقائيًا عند حدوث شيء ما في رحلة التحقق من الهوية. فبدلاً من أن يسأل نظامك "هل انتهى الأمر بعد؟"، يستدعي IDCloud واجهة برمجة التطبيقات الخاصة بك في اللحظة التي يحدث فيها الحدث.

في هذه الشاشة، تحدد عنوان واجهة برمجة التطبيقات الخاصة بك، وكيفية مصادقة IDCloud عليها، وما يحدث عندما لا تستجيب.

معلومة

لمن هذه الميزة: للعملاء الذين يريدون استلام نتائج الرحلة تلقائيًا، دون الحاجة إلى الاستقصاء (polling). تنطبق على تكاملات byUnico وbyClient على حد سواء.

ما يتغير في نظامك: يستقبل الآن إشعارًا عند كل تغيير في الحالة، بدلاً من الحاجة إلى استقصاء IDCloud.

أين تجدها: بوابة IDCloud ← الشريط الجانبي الإعدادات (Settings) ← علامة التبويب Webhook.

قبل وجود هذه الشاشة، كان أي تغيير في الـ webhook يتطلب فتح تذكرة دعم — نحو 30 تذكرة شهريًا لهذا الغرض فقط. أما الآن، يمكنك القيام بذلك بنفسك، في دقائق، في كل من بيئتي Staging وProduction.

قبل أن تبدأ

إذن الوصول

يحتاج مستخدمك إلى ملف تعريف Configurator — وهو نفس الملف الذي يمنح الوصول إلى تخصيص الرحلة (Journey Customization). إذا لم تظهر علامة تبويب Webhook، تحدث مع مسؤول حسابك.

كيفية تطبيق التكوين

النطاق (Scope)	webhook واحد لكل مستأجر (tenant) وفرع (branch). لا توجد قائمة: إذا كان هناك webhook مُهيّأ مسبقًا، يتم تعديله، وليس تكراره.
بيئات منفصلة	بوابة Staging تُهيّئ webhook بيئة UAT؛ وبوابة Production تُهيّئ بيئة Production. تهيئة إحداهما لا تؤثر على الأخرى.
متى يصبح ساري المفعول	بمجرد الحفظ.
أمان السر (Secret)	يتم تشفير السر ولا يُعرض بنص عادي مرة أخرى أبدًا. يظهر دائمًا مُقنّعًا (masked) على الشاشة.

ما يجب تجهيزه مسبقًا

• عنوان URL بصيغة HTTPS لواجهة برمجة التطبيقات الخاصة بك التي ستستلم الإشعارات. يجب أن يكون نشطًا ويقبل الطلبات قبل الحفظ.
• بيانات الاعتماد (credentials) التي تتوقعها واجهة برمجة التطبيقات الخاصة بك، بناءً على طريقة المصادقة التي تختارها (راجع الخطوة 3).
• إذا كانت واجهة برمجة التطبيقات الخاصة بك تخضع لحد أقصى للسعة، عدد الطلبات في الثانية التي تدعمها.

ما يجب تحديده مسبقًا

يعتمد قراران تقنيان على الجهة التي تُدير واجهة برمجة التطبيقات الخاصة بك، لا على من يُشغّل البوابة. يجدر مواءمتهما قبل فتح الشاشة:

• طريقة المصادقة التي تتطلبها واجهة برمجة التطبيقات الخاصة بك.
• ما إذا كنت ستُعدّل إعادة المحاولات (retries) أو ستتركها على الإعدادات الافتراضية. الإعداد الافتراضي يناسب معظم الحالات.

خطوة بخطوة

الخطوة 1 — افتح علامة تبويب Webhook

في بوابة IDCloud، انقر على أيقونة الترس (الإعدادات) في الشريط الجانبي، وحدد علامة التبويب Webhook.

إذا لم يكن لديك webhook مُهيّأ حتى الآن، تعرض الشاشة "لا توجد webhooks تم إنشاؤها" وزر إنشاء webhook. أما إذا كان لديك webhook مسبقًا، تعرض الشاشة بطاقة webhook الخاص بك مع نقطة النهاية (endpoint) ونوع المصادقة والسر المُقنّع، بالإضافة إلى زر تكوين webhook لتعديله.

بطاقة "webhook الخاص بك" مع نقطة النهاية ونوع المصادقة والسر المُقنّع.

الخطوة 2 — أدخل عنوان URL لواجهة برمجة التطبيقات الخاصة بك

انقر على إنشاء webhook (أو تكوين webhook، إذا كان موجودًا مسبقًا) واملأ حقل Client URL (Endpoint)، أسفل "معلومات العميل (Client information)".

هذا هو العنوان الذي سيرسل إليه IDCloud الإشعارات. يجب أن يكون بصيغة HTTPS.

وجّهه إلى عنوان نشط بالفعل. يبدأ IDCloud باستدعاء هذا العنوان فور الحفظ. إذا لم يكن موجودًا بعد، فستفشل الإشعارات الأولى وتستهلك إعادة المحاولات قبل أن يلاحظ فريقك ذلك.

حقل نقطة النهاية، مع النص التوضيحي حول متطلب HTTPS.

الخطوة 3 — اختر كيفية مصادقة IDCloud على واجهة برمجة التطبيقات الخاصة بك

أسفل "المصادقة (Authentication)"، حدد نوع المصادقة (Authentication type). توجد أربعة خيارات، ويطلب كل منها حقولًا مختلفة:

النوع	الحقول المعروضة	الحالة المناسبة للاستخدام
None	لا يوجد	واجهة برمجة التطبيقات الخاصة بك لا تتطلب مصادقة. استخدم هذا الخيار فقط إذا كانت محمية بطريقة أخرى — فبدون أي مصادقة، يمكن لأي شخص يكتشف عنوان URL إرسال بيانات إليها
API Key	Secret	واجهة برمجة التطبيقات الخاصة بك تتحقق من مفتاح ثابت
Basic Auth	Secret	واجهة برمجة التطبيقات الخاصة بك تستخدم اسم مستخدم وكلمة مرور، على طراز HTTP Basic
OAuth 2.0	Auth URL، Client ID، Secret	واجهة برمجة التطبيقات الخاصة بك تتطلب رمزًا (token). يجلب IDCloud الرمز من ذلك العنوان ويجدده بنفسه

بالنسبة لـ OAuth 2.0، فإن Auth URL هو العنوان الذي يجلب IDCloud الرمز منه — وليس العنوان الذي يستلم الإشعارات. إنهما عنوانان مختلفان، وتبديلهما هو الخطأ الأكثر شيوعًا في هذه الشاشة.

يُخزَّن Secret مُشفّرًا. عند تعديل webhook موجود، يظهر الحقل فارغًا: تعبئته تستبدل السر الحالي، وتركه فارغًا يحتفظ بما هو موجود مسبقًا.

تأكد من طريقة المصادقة مع الجهة التي تُدير واجهة برمجة التطبيقات الخاصة بك قبل الحفظ. المصادقة الخاطئة لا تُنتج خطأ على الشاشة — بل تُنتج إشعارًا يفشل بصمت بعد ذلك، ولا تكتشف الأمر إلا عندما لا تصل نتيجة.

حقل نوع المصادقة وحقول بيانات الاعتماد المقابلة.

الخطوة 4 — اضبط إعادة المحاولات، إذا لزم الأمر

قسم تكوين إعادة المحاولة (Retry configuration) اختياري ويكون مغلقًا في البداية. لا تُفعّله إلا إذا احتجت إلى تغيير السلوك الافتراضي.

تفعيله يكشف عن ستة حقول:

الحقل	ما يتحكم به	الافتراضي
Maximum retries	عدد مرات إعادة المحاولة التي يقوم بها IDCloud قبل التوقف	—
Rate limit (req/s)	الحد الأقصى للإشعارات في الثانية. قلّله إذا كانت واجهة برمجة التطبيقات الخاصة بك محدودة السعة	—
Minimum time (s)	الفترة الزمنية الدنيا بين المحاولات	2 ثانية
Maximum time (s)	الفترة الزمنية القصوى بين المحاولات	10 ثوانٍ
Maximum duration (s)	مدة الانتظار لكل محاولة قبل اعتبارها فاشلة	2 ثانية
Maximum doublings	عامل نمو الفترة الزمنية بين المحاولات (التراجع التصاعدي/backoff)	5

السلوك المُجمّع: يحاول IDCloud، ينتظر الفترة الزمنية الدنيا (minimum time)، يحاول مرة أخرى، ويستمر في زيادة الفترة الزمنية وفقًا لـ maximum doublings حتى الفترة الزمنية القصوى (maximum time) — ويتكرر ذلك إلى أن يصل إلى maximum retries. كل محاولة فردية تتوقف بعد maximum duration.

اضبط الـ Rate limit قبل تعديل أي شيء آخر. إذا كانت واجهة برمجة التطبيقات الخاصة بك تنهار تحت الضغط، فالمشكلة في الإنتاجية (throughput)، وليست في إعادة المحاولات — وزيادة إعادة المحاولات في هذا السيناريو تزيد الأمر سوءًا، لأنها تُضاعف عدد الاستدعاءات. اخفض معدل الطلبات أولًا.

زيادة Maximum retries لا تُعوّض عن واجهة برمجة تطبيقات مستقرة. إعادة المحاولات تُغطي حالات عدم التوفر اللحظية. إذا كانت واجهة برمجة التطبيقات الخاصة بك تفشل بشكل متكرر، فهذا الإعداد يؤخر فقط اللحظة التي تفقد فيها الإشعار.

الحقول الستة لإعادة المحاولة، تظهر بعد تفعيل المفتاح.

الخطوة 5 — احفظ

انقر على حفظ (Save). إلغاء (Cancel) يتجاهل كل شيء ويحتفظ بالتكوين السابق.

يتحقق IDCloud من صحة عنوان URL للرمز (token URL) قبل السماح لك بالحفظ، عندما تكون الطريقة هي OAuth 2.0.

بعد الحفظ، تعرض بطاقة webhook الخاص بك نقطة النهاية ونوع المصادقة. يظهر السر مُقنّعًا ولا يمكن استرجاعه من الشاشة بعد ذلك — إذا فقدت القيمة، ستحتاج إلى تعيين قيمة جديدة.

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

الأسئلة الشائعة

هل يمكنني تسجيل أكثر من webhook واحد؟ لا. يوجد webhook واحد فقط لكل مستأجر وفرع. إذا كان هناك واحد موجود مسبقًا، يتم تعديله — ولا توجد طريقة لإنشاء webhook ثانٍ.

قمت بتهيئته في Staging. هل ينطبق على Production أيضًا؟ لا. البيئتان مستقلتان: بوابة Staging تُهيّئ webhook بيئة UAT، وبوابة Production تُهيّئ بيئة Production. تحتاج إلى تكرار التكوين في بوابة Production.

كيف أرى السر الذي سجّلته؟ لا يمكنك ذلك. يتم تشفيره عند الحفظ ويُعرض دائمًا مُقنّعًا. إذا فقدت القيمة، سجّل قيمة جديدة عبر حقل Secret — تعبئته تستبدل القيمة السابقة.

عدّلت الـ webhook ولا أريد تغيير السر. ما الذي أفعله؟ اترك حقل Secret فارغًا. تُحفظ القيمة الحالية كما هي.

كيف أحذف webhook؟ لا تُقدّم الشاشة خيار الحذف. لإزالة التكوين، تواصل مع دعم Unico. إذا كان الهدف هو فقط التوقف عن استلام الإشعارات أو تغيير الوجهة، فعدّل عنوان URL بدلاً من ذلك.

قمت بالحفظ والإشعارات لا تصل. تحقق، بهذا الترتيب: أن عنوان URL صحيح وبصيغة HTTPS؛ أن واجهة برمجة التطبيقات الخاصة بك نشطة؛ أن طريقة المصادقة هي ما تتوقعه؛ وأن السر أُدخل بشكل صحيح. لا تظهر أخطاء المصادقة كخطأ في هذه الشاشة — بل تحدث وقت التسليم.

ما الفرق بين "Maximum duration" و"Maximum time"؟ "Maximum time" هي أطول فترة زمنية بين محاولتين. "Maximum duration" هي مدة انتظار IDCloud لكل محاولة قبل اعتبارها فاشلة.

هل أحتاج إلى webhook إذا كنت أستقصي (poll) النتيجة عبر واجهة برمجة التطبيقات بالفعل؟ ليس ضروريًا، لكنه يُوفّر على نظامك عملية الاستقصاء. إذا كانت لديك بالفعل عملية استقصاء تعمل بشكل جيد، فالـ webhook تحسين إضافي، وليس ضرورة.

مرجع سريع

بوابة IDCloud
 └─ الإعدادات (أيقونة الترس في الشريط الجانبي)
     └─ علامة تبويب Webhook
         ├─ معلومات العميل ....... Client URL (Endpoint)، HTTPS
         ├─ المصادقة ............ None | API Key | Basic Auth | OAuth 2.0
         │                        OAuth 2.0: + Auth URL و Client ID
         └─ إعادة المحاولات (اختياري) ....... Maximum retries
                                       Rate limit (req/s)
                                       Minimum time (2s) · Maximum time (10s)
                                       Maximum duration (2s) · Maximum doublings (5)

webhook واحد لكل مستأجر وفرع · UAT و Production مستقلتان · السر لا يُعرض أبدًا · إلغاء · حفظ