#Webhook

#مقدمة

يُستخدم مشغل Webhook لتوفير عنوان URL يمكن لأنظمة الطرف الثالث استدعاؤه عبر طلبات HTTP. عندما يحدث حدث من طرف ثالث، يتم إرسال طلب HTTP إلى هذا العنوان لتشغيل تنفيذ سير العمل. هذا مناسب للإشعارات التي تبدأها أنظمة خارجية، مثل إشعارات الدفع (callbacks) والرسائل وغيرها.

#إنشاء سير عمل

عند إنشاء سير عمل، اختر النوع "حدث Webhook":

#إعدادات المشغل

#عنوان URL لـ Webhook

يتم إنشاء عنوان URL لمشغل Webhook تلقائيًا بواسطة النظام ويرتبط بسير العمل هذا. يمكنك النقر على الزر الموجود على اليمين لنسخه ولصقه في نظام الطرف الثالث.

طريقة HTTP المدعومة هي POST فقط؛ أي طرق أخرى ستُرجع خطأ 405.

#الأمان

يدعم النظام حاليًا مصادقة HTTP الأساسية (Basic Authentication). يمكنك تفعيل هذا الخيار وتعيين اسم مستخدم وكلمة مرور، ثم تضمين اسم المستخدم وكلمة المرور في عنوان URL لـ Webhook في نظام الطرف الثالث لتحقيق مصادقة آمنة لـ Webhook (للاطلاع على تفاصيل المعيار، راجع: MDN: مصادقة HTTP).

عند تعيين اسم مستخدم وكلمة مرور، سيتحقق النظام مما إذا كان اسم المستخدم وكلمة المرور في الطلب متطابقين. إذا لم يتم توفيرهما أو لم يتطابقا، فسيتم إرجاع خطأ 401.

#تحليل بيانات الطلب

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

ينقسم تحليل طلب HTTP إلى ثلاثة أجزاء:

1. رؤوس الطلب

   عادةً ما تكون رؤوس الطلب عبارة عن أزواج بسيطة من المفتاح والقيمة من نوع السلسلة النصية. يمكن تكوين حقول الرأس التي تحتاج إلى استخدامها مباشرةً، مثل Date و X-Request-Id وما إلى ذلك.

2. معاملات الطلب

   معاملات الطلب هي جزء معاملات الاستعلام (query parameters) في عنوان URL، مثل المعامل query في http://localhost:13000/api/webhook:trigger/1hfmkioou0d?query=1. يمكنك لصق عنوان URL كامل كنموذج أو جزء معاملات الاستعلام فقط، ثم النقر على زر التحليل لتحليل أزواج المفتاح والقيمة تلقائيًا.

   

   سيقوم التحليل التلقائي بتحويل جزء المعاملات من عنوان URL إلى بنية JSON، ويُنشئ مسارات مثل query[0] و query[0].a بناءً على التسلسل الهرمي للمعاملات. يمكن تعديل اسم المسار يدويًا إذا لم يلبي احتياجاتك، ولكن عادةً لا يكون التعديل ضروريًا. الاسم المستعار هو اسم عرض المتغير عند استخدامه، وهو اختياري. في الوقت نفسه، سيُنشئ التحليل جدولًا كاملاً للمعاملات من النموذج؛ يمكنك حذف أي معاملات لا تحتاج إلى استخدامها.

3. نص الطلب

   نص الطلب هو جزء Body من طلب HTTP. حاليًا، يتم دعم نصوص الطلب التي يكون Content-Type الخاص بها application/json فقط. يمكنك تكوين المسارات التي تحتاج إلى تحليلها مباشرةً، أو يمكنك إدخال نموذج JSON والنقر على زر التحليل لإجراء تحليل تلقائي.

   

   سيقوم التحليل التلقائي بتحويل أزواج المفتاح والقيمة في بنية JSON إلى مسارات. على سبيل المثال، {"a": 1, "b": {"c": 2}} سيُنشئ مسارات مثل a و b و b.c. الاسم المستعار هو اسم عرض المتغير عند استخدامه، وهو اختياري. في الوقت نفسه، سيُنشئ التحليل جدولًا كاملاً للمعاملات من النموذج؛ يمكنك حذف أي معاملات لا تحتاج إلى استخدامها.

#إعدادات الاستجابة

تختلف طريقة تكوين استجابة Webhook بين سير العمل المتزامن وغير المتزامن. بالنسبة لسير العمل غير المتزامن، يتم تكوين الاستجابة مباشرةً في المشغل. عند تلقي طلب Webhook، يتم إرجاع الاستجابة المكونة فورًا إلى نظام الطرف الثالث، ثم يتم تنفيذ سير العمل. أما بالنسبة لسير العمل المتزامن، فيجب إضافة عقدة استجابة ضمن التدفق للتعامل معها وفقًا لمتطلبات العمل (للتفاصيل، راجع: عقدة الاستجابة).

عادةً، يكون رمز حالة الاستجابة لحدث Webhook الذي يتم تشغيله بشكل غير متزامن هو 200، ونص الاستجابة هو ok. يمكنك أيضًا تخصيص رمز حالة الاستجابة ورؤوس الاستجابة ونص الاستجابة حسب الحاجة.

#عقدة الاستجابة

المرجع: عقدة الاستجابة

#مثال

في سير عمل Webhook، يمكنك إرجاع استجابات مختلفة بناءً على شروط العمل المختلفة، كما هو موضح في الشكل أدناه:

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