#دمج Webhook في سير العمل

باستخدام مشغلات Webhook، يمكن لـ NocoBase استقبال استدعاءات HTTP من أنظمة خارجية وتشغيل سير العمل تلقائيًا، مما يتيح دمجًا سلسًا مع هذه الأنظمة.

#نظرة عامة

Webhook هي آلية "واجهة برمجة تطبيقات عكسية" (Reverse API) تسمح للأنظمة الخارجية بإرسال البيانات بشكل استباقي إلى NocoBase عند وقوع أحداث معينة. مقارنة بالاستقصاء النشط (Active Polling)، توفر Webhook طريقة دمج أكثر فورية وفعالية.

#حالات الاستخدام الشائعة

#إرسال بيانات النماذج

تقوم أنظمة استبيانات خارجية، ونماذج تسجيل، ونماذج ملاحظات العملاء، وغيرها، بعد قيام المستخدم بإرسال البيانات، بدفع هذه البيانات إلى NocoBase عبر Webhook، مما يؤدي إلى إنشاء سجلات تلقائيًا وتشغيل عمليات معالجة لاحقة (مثل إرسال رسائل بريد إلكتروني للتأكيد، وتعيين المهام، وما إلى ذلك).

#إشعارات الرسائل

يمكن لأحداث من منصات مراسلة خارجية (مثل WeCom، DingTalk، Slack) كرسائل جديدة، أو إشارات (@)، أو اكتمال الموافقات، أن تشغل عمليات المعالجة التلقائية في NocoBase عبر Webhooks.

#مزامنة البيانات

عندما تتغير البيانات في أنظمة خارجية (مثل CRM، ERP)، تقوم Webhooks بدفع التحديثات إلى NocoBase في الوقت الفعلي للحفاظ على مزامنة البيانات.

#دمج الخدمات الخارجية

• GitHub: دفعات الكود، أحداث إنشاء طلبات السحب (PR) تشغل سير العمل التلقائي.
• GitLab: إشعارات حالة مسار CI/CD.
• إرسال النماذج: أنظمة النماذج الخارجية ترسل البيانات إلى NocoBase.
• أجهزة إنترنت الأشياء (IoT): تغييرات حالة الجهاز، إبلاغ بيانات المستشعرات.

#الميزات

#آلية تشغيل مرنة

• تدعم طرق HTTP مثل GET، POST، PUT، DELETE.
• تحلل تلقائيًا تنسيقات شائعة مثل JSON وبيانات النماذج.
• إمكانية تهيئة التحقق من الطلبات لضمان مصادر موثوقة.

#قدرات معالجة البيانات

• يمكن استخدام البيانات المستلمة كمتغيرات في سير العمل.
• تدعم منطق تحويل ومعالجة البيانات المعقدة.
• يمكن دمجها مع عقد سير العمل الأخرى لتنفيذ منطق أعمال معقد.

#ضمان الأمان

• تدعم التحقق من التوقيع لمنع الطلبات المزورة.
• قائمة IP بيضاء قابلة للتهيئة.
• نقل مشفر عبر HTTPS.

#خطوات الاستخدام

#1. تثبيت الإضافة

ابحث عن سير العمل: مشغل Webhook وقم بتثبيتها في مدير الإضافات.

ملاحظة: هذه إضافة تجارية تتطلب شراءً أو اشتراكًا منفصلاً.

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

1. انتقل إلى صفحة إدارة سير العمل.
2. انقر على إنشاء سير عمل.
3. اختر مشغل Webhook كنوع للمشغل.

4. قم بتهيئة معلمات Webhook.

• مسار الطلب: مسار URL مخصص لـ Webhook.
• طريقة الطلب: اختر طرق HTTP المسموح بها (GET/POST/PUT/DELETE).
• متزامن/غير متزامن: اختر ما إذا كنت تريد الانتظار حتى اكتمال تنفيذ سير العمل قبل إرجاع النتائج.
• طريقة التحقق: قم بتهيئة التحقق من التوقيع أو آليات أمان أخرى.

#3. تهيئة عقد سير العمل

أضف عقد سير العمل بناءً على متطلبات العمل، مثل:

• عمليات المجموعة: إنشاء، تحديث، حذف السجلات.
• المنطق الشرطي: التفرع بناءً على البيانات المستلمة.
• طلب HTTP: استدعاء واجهات برمجة تطبيقات (APIs) أخرى.
• الإشعارات: إرسال رسائل بريد إلكتروني، رسائل نصية قصيرة (SMS)، وما إلى ذلك.
• كود مخصص: تنفيذ كود JavaScript.

#4. الحصول على رابط Webhook

بعد إنشاء سير العمل، يقوم النظام بإنشاء رابط Webhook فريد، يكون تنسيقه عادةً:

https://your-nocobase-domain.com/api/webhooks/your-workflow-key

#5. التهيئة في نظام خارجي

قم بتهيئة رابط Webhook الذي تم إنشاؤه في النظام الخارجي:

• في أنظمة النماذج، قم بتعيين عنوان رد الاتصال لإرسال البيانات.
• قم بتهيئة Webhook في GitHub/GitLab.
• قم بتهيئة عنوان دفع الأحداث في WeCom/DingTalk.

#6. اختبار Webhook

اختبر Webhook باستخدام أدوات مثل Postman أو cURL:

curl -X POST https://your-nocobase-domain.com/api/webhooks/your-workflow-key \
  -H "Content-Type: application/json" \
  -d '{"event":"test","data":{"message":"Hello NocoBase"}}'

#الوصول إلى بيانات الطلب

في سير العمل، يمكنك الوصول إلى بيانات Webhook المستلمة عبر المتغيرات:

• {{$context.data}}: بيانات نص الطلب
• {{$context.headers}}: معلومات رؤوس الطلب
• {{$context.query}}: معلمات استعلام URL
• {{$context.params}}: معلمات المسار

#تهيئة الاستجابة

#الوضع المتزامن

يعيد النتائج بعد اكتمال تنفيذ سير العمل، ويمكن تهيئته كالتالي:

• رمز حالة الاستجابة: 200، 201، إلخ.
• بيانات الاستجابة: بيانات JSON مخصصة يتم إرجاعها.
• رؤوس الاستجابة: رؤوس HTTP مخصصة.

#الوضع غير المتزامن

يعيد تأكيدًا فوريًا، ويتم تنفيذ سير العمل في الخلفية. مناسب لـ:

• سير العمل الذي يستغرق وقتًا طويلاً.
• السيناريوهات التي لا تتطلب إرجاع نتائج التنفيذ.
• سيناريوهات التزامن العالي.

#أفضل ممارسات الأمان

#1. تمكين التحقق من التوقيع

تدعم معظم الخدمات الخارجية آليات التوقيع:

// مثال: التحقق من توقيع GitHub Webhook
const crypto = require('crypto');
const signature = context.headers['x-hub-signature-256'];
const payload = JSON.stringify(context.data);
const secret = 'your-webhook-secret';
const expectedSignature = 'sha256=' + crypto
  .createHmac('sha256', secret)
  .update(payload)
  .digest('hex');

if (signature !== expectedSignature) {
  throw new Error('Invalid signature');
}

#2. استخدام HTTPS

تأكد من نشر NocoBase في بيئة HTTPS لحماية نقل البيانات.

#3. تقييد مصادر الطلبات

قم بتهيئة قائمة IP بيضاء للسماح بالطلبات من المصادر الموثوقة فقط.

#4. التحقق من صحة البيانات

أضف منطق التحقق من صحة البيانات في سير العمل لضمان صحة تنسيق البيانات المستلمة ومحتواها.

#5. تدقيق السجلات

سجل جميع طلبات Webhook لتسهيل التتبع واستكشاف الأخطاء وإصلاحها.

#استكشاف الأخطاء وإصلاحها

#Webhook لا يعمل؟

1. تحقق من صحة رابط Webhook.
2. تأكد من أن حالة سير العمل هي "مفعل".
3. راجع سجلات الإرسال في النظام الخارجي.
4. راجع تهيئة جدار الحماية والشبكة.

#كيف يمكنني تصحيح أخطاء Webhook؟

1. راجع سجلات تنفيذ سير العمل للحصول على معلومات مفصلة حول الطلبات والنتائج.
2. استخدم أدوات اختبار Webhook (مثل Webhook.site) للتحقق من الطلبات.
3. راجع البيانات الرئيسية ورسائل الخطأ في سجلات التنفيذ.

#كيف تتعامل مع عمليات إعادة المحاولة؟

تعيد بعض الخدمات الخارجية إرسال الطلبات إذا لم تتلق استجابة ناجحة:

• تأكد من أن سير العمل يتمتع بخاصية التكرارية (idempotent).
• استخدم معرفات فريدة لإزالة التكرارات.
• سجل معرفات الطلبات التي تم معالجتها.

#نصائح لتحسين الأداء

• استخدم الوضع غير المتزامن لمعالجة العمليات التي تستغرق وقتًا طويلاً.
• أضف منطقًا شرطيًا لتصفية الطلبات غير الضرورية.
• فكر في استخدام قوائم انتظار الرسائل لمعالجة سيناريوهات التزامن العالي.

#سيناريوهات أمثلة

#معالجة إرسال النماذج الخارجية

// 1. التحقق من مصدر البيانات
// 2. تحليل بيانات النموذج
const formData = context.data;

// 3. إنشاء سجل عميل
// 4. التعيين للمسؤول المعني
// 5. إرسال بريد إلكتروني للتأكيد إلى المرسل
if (formData.email) {
  // إرسال إشعار عبر البريد الإلكتروني
}

#إشعار دفع كود GitHub

// 1. تحليل بيانات الدفع
const commits = context.data.commits;
const branch = context.data.ref.replace('refs/heads/', '');

// 2. إذا كان الفرع الرئيسي
if (branch === 'main') {
  // 3. تشغيل عملية النشر
  // 4. إخطار أعضاء الفريق
}

#موارد ذات صلة

• وثائق إضافة سير العمل
• سير العمل: مشغل Webhook
• سير العمل: عقدة طلب HTTP
• مصادقة مفاتيح API