Webhook
Webhook هو الطريقة التي يُخبر بها IDCloud نظامك تلقائيًا عند حدوث شيء ما في رحلة التحقق من الهوية. فبدلاً من أن يسأل نظامك "هل انتهى الأمر بعد؟"، يستدعي IDCloud واجهة برمجة التطبيقات الخاصة بك في اللحظة التي يحدث فيها الحدث.
في هذه الشاشة، تحدد عنوان واجهة برمجة التطبيقات الخاصة بك، وكيفية مصادقة IDCloud عليها، وما يحدث عندما لا تستجيب.
لمن هذه الميزة: للعملاء الذين يريدون استلام نتائج الرحلة تلقائيًا، دون الحاجة إلى الاستقصاء (polling). تنطبق على جميع أنواع التكامل.
ما يتغير في نظامك: يستقبل الآن إشعارًا عند كل تغيير في الحالة، بدلاً من الحاجة إلى استقصاء IDCloud.
أين تجدها: بوابة IDCloud ← الشريط الجانبي الإعدادات (Settings) ← علامة التبويب Webhook.
قبل أن تبدأ
إذن الوصول
يحتاج مستخدمك إلى ملف تعريف 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 الرمز من ذلك العنوان ويجدده بنفسه |
| mTLS | شهادة العميل، المفتاح الخاص، CA الخادم (اختياري) | واجهة برمجة التطبيقات الخاصة بك لا تقبل إلا الاستدعاءات من العملاء الذين يقدّمون شهادة (TLS المتبادل). يقدّم IDCloud الشهادة التي تقدّمها مع كل إشعار |
بالنسبة لـ OAuth 2.0، فإن Auth URL هو العنوان الذي يجلب IDCloud الرمز منه — وليس العنوان الذي يستلم الإشعارات. إنهما عنوانان مختلفان، وتبديلهما هو الخطأ الأكثر شيوعًا في هذه الشاشة.
يُخزَ ّن Secret مُشفّرًا. عند تعديل webhook موجود، يظهر الحقل فارغًا: تعبئته تستبدل السر الحالي، وتركه فارغًا يحتفظ بما هو موجود مسبقًا.
تأكد من طريقة المصادقة مع الجهة التي تُدير واجهة برمجة التطبيقات الخاصة بك قبل الحفظ. المصادقة الخاطئة لا تُنتج خطأ على الشاشة — بل تُنتج إشعارًا يفشل بصمت بعد ذلك، ولا تكتشف الأمر إلا عندما لا تصل نتيجة.

حقل نوع المصادقة وحقول بيانات الاعتماد المقابلة.
إعداد mTLS
مع mTLS، يُعرّف IDCloud بنفسه لدى واجهة برمجة التطبيقات الخاصة بك بتقديم شهادة عميل (TLS المتبادل)، بدلًا من إرسال مفتاح أو كلمة مرور أو رمز (token). يجب أن تكون واجهة برمجة التطبيقات الخاصة بك مُهيّأة لتطلب تلك الشهادة وتثق بالجهة التي أصدرتها. عند اختيار mTLS تظهر ثلاثة حقول:
| الحقل | ما يجب تقديمه |
|---|---|
| شهادة العميل (PEM) | سلسلة الشهادات بتنسيق PEM، مع الشهادة الطرفية (leaf) أولًا. أضف الشهادات الوسيطة بعد شهادتك، حتى تتمكن واجهة برمجة التطبيقات الخاصة بك من ربط الشهادة بهيئة شهادات تثق بها |
| المفتاح الخاص (PEM) | المفتاح المقترن بالشهادة، بتنسيق PEM وبدون كلمة مرور. يُخزَّن مُشفّرًا ولا يُعرض مرة أخرى أبدًا |
| CA الخادم (PEM، اختياري) | فقط إذا كانت شهادة واجهة برمجة التطبيقات الخاصة بك نفسها موقَّعة من هيئة شهادات خاصة. بدونه، يثق IDCloud بهيئات الشهادات العامة |
يمكنك اختيار ملف .pem أو لصق النص. يقبل كل حقل حتى 20,000 حرف.
بعض القواعد التي يجب معرفتها قبل اختيار mTLS:
- يجب أن يكون عنوان URL بصيغة HTTPS، ويجب أن تقبل واجهة برمجة التطبيقات الخاصة بك TLS 1.2 أو أحدث.
- بعد الحفظ، يصبح النوع مقفلًا. لا يمكن تغيير نوع المصادقة إلى نوع آخر في هذه الشاشة. لتغيير الطريقة، تواصل مع دعم Unico.
- لا يتم إرسال أي بيانات اعتماد أخرى. لا يمكن دمج mTLS مع API Key أو Basic Auth أو OAuth 2.0 في الـ webhook نفسه.
- تُعدّ عمليات إعادة التوجيه حالات فشل. لا يتّبعها IDCloud، لذا وجّه عنوان URL إلى العنوان النهائي.
الخطوة 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. أما مع mTLS، فيتحقق من الشهادة والمفتاح بدلًا من ذلك: يجب أن يكون كلاهما بتنسيق PEM، وألا يكون المفتاح محميًا بكلمة مرور وأن يطابق الشهادة، وأن تكون الشهادة ضمن فترة صلاحيتها.
بعد الحفظ، تعرض بطاقة webhook الخاص بك نقطة النهاية ونوع المصادقة. يظهر السر مُقنّعًا ولا يمكن استرجاعه من الشاشة بعد ذلك — إذا فقدت القيمة، ستحتاج إلى تعيين قيمة جديدة.
قم باختبار حقيقي قبل اعتبار المهمة منتهية. ابدأ رحلة في بيئة Staging وتأكد من أن الإشعار وصل إلى واجهة برمجة التطبيقات الخاصة بك. الشاشة تؤكد أن التكوين تم حفظه، لا أن واجهة برمجة التطبيقات الخاصة بك استلمته.
الأسئلة الشائعة
هل يمكنني تسجيل أكثر من webhook واحد؟ لا. يوجد webhook واحد فقط لكل مستأجر وفرع. إذا كان هناك واحد موجود مسبقًا، يتم تعديله — ولا توجد طريقة لإنشاء webhook ثانٍ.
قمت بتهيئته في Staging. هل ينطبق على Production أيضًا؟ لا. البيئتان مستقلتان: بوابة Staging تُهيّئ webhook بيئة UAT، وبوابة Production تُهيّئ بيئة Production. تحتاج إلى تكرار التكوين في بوابة Production.
كيف أرى السر الذي سجّلته؟ لا يمكنك ذلك. يتم تشفيره عند الحفظ ويُعرض دائمًا مُقنّعًا. إذا فقدت القيمة، سجّل قيمة جديدة عبر حقل Secret — تعبئته تستبدل القيمة السابقة.
عدّلت الـ webhook ولا أريد تغيير السر. ما الذي أفعله؟ اترك حقل Secret فارغًا. تُحفظ القيمة الحالية كما هي.
كيف أستبدل شهادة mTLS قبل انتهاء صلاحيتها؟ عدّل الـ webhook. تظهر الشهادة والمفتاح الخاص مُقنّعين. قدّم الشهادة الجديدة والمفتاح الخاص الجديد — كلاهما مطلوب، حتى لو تغيّر أحدهما فقط — وكذلك CA الخادم مرة أخرى، إذا كنت تستخدمه. ثم احفظ. يبدأ IDCloud باستخدام الشهادة الجديدة خلال نحو 5 دقائق، لذا أبقِ الشهادة السابقة صالحة لفترة أطول قليلًا من ذلك قبل إبطالها. إذا تركت الحقول الثلاثة دون تغيير، تظل الشهادة الحالية قيد الاستخدام.
هل يمكنني التبديل من mTLS إلى نوع مصادقة آخر؟ ليس في هذه الشاشة: بعد الحفظ، يصبح النوع مقفلًا. تواصل مع دعم Unico لإزالة تكوين الـ webhook، ثم أنشئه من جديد بالطريقة الجديدة.
كيف أحذف webhook؟ لا تُقدّم الشاشة خيار الحذف. لإزالة التكوين، تواصل مع دعم Unico. إذا كان الهدف هو فقط التوقف عن استلام الإشعارات أو تغيير الوجهة، فعدّل عنوان URL بدلاً من ذلك.
قمت بالحفظ والإشعارات لا تصل. تحقق، بهذا الترتيب: أن عنوان URL صحيح وبصيغة HTTPS؛ أن واجهة برمجة التطبيقات الخاصة بك نشطة؛ أن طريقة المصادقة هي ما تتوقعه؛ وأن السر أُدخل بشكل صحيح. مع mTLS، تحقق أيضًا من أن واجهة برمجة التطبيقات الخاصة بك تثق بالجهة التي أصدرت الشهادة، ومن أن صلاحية الشهادة لم تنتهِ، ومن تعبئة حقل CA الخادم إذا كانت شهادة واجهة برمجة التطبيقات الخاصة بك صادرة عن هيئة شهادات خاصة. لا تظهر أخطاء المصادقة كخطأ في هذه الشاشة — بل تحدث وقت التسليم.
ما الفرق بين "Maximum duration" و"Maximum time"؟ "Maximum time" هي أطول فترة زمنية بين محاولتين. "Maximum duration" هي مدة انتظار IDCloud