RAPTIX دليل المستخدم English افتح RAPTIX

مُشغّل Webhook: بدء سير العمل من الأنظمة الخارجية عبر API

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

ما هو؟

يمنح مُشغّل Webhook في مسارات سير العمل، الذي يحمل اسم عند استدعاء Webhook (On Webhook Call) في إعدادات عقدة البداية، كل سير عمل نقطة نهاية HTTP فريدة؛ وهي عنوان URL يستطيع أي نظام خارجي استدعاءه لبدء مثيل جديد. عندما يرسل نظام مخوّل طلب HTTP إلى ذلك العنوان بالبيانات المتوقعة، يبدأ تشغيل جديد فورًا وتتاح البيانات المرسلة كمتغيرات في كل أنحاء العملية.

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

أهميته وفوائده الرئيسية

  • بدء سير العمل من أي نظام يرسل طلبات HTTP. تستطيع مُشغّلات ERP وأتمتة البريد وأنظمة التذاكر والبرامج النصية المجدولة وتكاملات الأطراف الخارجية بدء عمليات سير العمل باستدعاء عنوان URL، من دون تسجيل الدخول إلى المنصة.
  • لكل سير عمل عنوان مخصص مستقل. لا يوجد مفتاح API مشترك يؤثر في جميع المسارات. كل عنوان Webhook خاص بسير عمل واحد ولا يحمل إلا بيانات تلك العملية.
  • تتحول البيانات الواردة فورًا إلى متغيرات سير عمل. تصبح الحقول التي تعرّفها في مخطط الحمولة متغيرات مسماة متاحة في أوصاف المهام وعُقد البريد والشروط وكل عقدة لاحقة من دون خطوة ربط.
  • خيارات مصادقة متعددة. اختر عدم المصادقة أو Bearer Token أو API Key أو Basic Auth بحسب ما يدعمه نظامك الخارجي.
  • أداة اختبار مضمّنة. أرسل طلب اختبار مباشرة من المصمم من دون مغادرة المتصفح، للتأكد من إمكانية الوصول إلى نقطة النهاية واستلام البيانات بصورة صحيحة.
  • تعمل المسارات التي يبدأها Webhook بموثوقية المسارات اليدوية نفسها. بعد البدء، يستمر المثيل طوال المدة اللازمة، سواء دقائق أو أيامًا أو أسابيع، ويستأنف من النقطة نفسها حتى بعد إعادة تشغيل الخادم، من دون فقد بيانات.

قبل أن تبدأ

  • يلزم دور المشرف لإعداد مُشغّل Webhook.
  • يجب حفظ سير العمل باسم، لا مجرد فتحه في المصمم، قبل توليد عنوان نقطة النهاية. تعرض المسارات بلا عنوان أو غير المحفوظة عنوانًا نائبًا.
  • لكي تستدعي الأنظمة الخارجية Webhook، يجب أن تتمكن شبكيًا من الوصول إلى نطاق RAPTIX الخاص بك: https://<workspace>.raptix.app.
  • لاستخدام Bearer Token أو API Key أو Basic Auth، ستحتاج إلى إنشاء بيانات الاعتماد أو الاتفاق عليها مع الفريق المالك للنظام الخارجي.

طريقة الاستخدام خطوة بخطوة

الخطوة 1 — فتح عقدة البداية واختيار مُشغّل Webhook

  1. افتح سير العمل في المصمم المرئي (Visual Designer) باختيار إجراء القلم في صفه ضمن إدارة سير العمل.

  2. انقر نقرًا مزدوجًا على عقدة البداية (Start)، ذات رمز التشغيل الذهبي أعلى اللوحة. تفتح لوحة اختيار المُشغّل.

  3. انقر عند استدعاء Webhook (On Webhook Call) في قائمة أنواع المُشغّلات. تتوسع اللوحة لعرض إعدادات Webhook.

الخطوة 2 — مراجعة عنوان نقطة النهاية ونسخه

تُنشأ نقطة النهاية تلقائيًا من اسم سير العمل، وتظهر في حقل نقطة النهاية (Endpoint) كقيمة للقراءة فقط.

  1. يعرض الحقل مسارًا مثل /api/v1/dynamic-workflow/http-start/your-workflow-name.

  2. يظهر أسفل الحقل العنوان الكامل باللون الأزرق:
    https://<workspace>.raptix.app/api/v1/dynamic-workflow/http-start/your-workflow-name

  3. انقر نسخ (Copy)، رمز الحافظة إلى يمين الحقل، لنسخ العنوان الكامل إلى الحافظة.

مهم: يتغير عنوان نقطة النهاية إذا تغيّر اسم سير العمل. حدّث كل الأنظمة الخارجية التي تحفظ العنوان كلما أعدت تسمية سير العمل.

الخطوة 3 — إعداد المصادقة

  1. اختر من قائمة المصادقة (Authentication) المنسدلة طريقة تعريف النظام الخارجي بنفسه:

    الخيار معناه
    بلا مصادقة (None) يستطيع أي مستدعٍ بدء سير العمل من دون بيانات اعتماد. استخدمه فقط في الشبكات الداخلية المحمية بجدار ناري أو للتطوير.
    Bearer Token يجب أن يضمّن المستدعي Authorization: Bearer <token> في رأس الطلب. مناسب لمعظم التكاملات الحديثة.
    API Key يجب أن يضمّن المستدعي رأس API Key. يُتفق على اسم المفتاح وقيمته بينك وبين النظام المستدعي.
    Basic Auth يجب أن يضمّن المستدعي Authorization: Basic <base64(username:password)> في الرأس.

  2. اختر الطريقة التي يطابقها نظامك الخارجي.

الخطوة 4 — تحديد طريقة HTTP

  1. اختر من قائمة الطريقة (Method) المنسدلة طريقة HTTP التي يستخدمها النظام الخارجي لإرسال الطلب:

    الطريقة متى تستخدمها؟
    POST موصى بها لمعظم التكاملات. ترسل البيانات في نص الطلب.
    GET استخدمها فقط عندما يتعذر على المستدعي إرسال نص للطلب، وهو أمر نادر. تأتي البيانات من معاملات الاستعلام فقط.
    PUT مثل POST، لكنها تشير دلاليًا إلى تحديث مورد قائم.
    DELETE نادرًا ما تُستخدم لمُشغّلات سير العمل.

    اتركها POST لمعظم التكاملات.

الخطوة 5 — تعريف رؤوس مخصصة اختياريًا

  1. إذا كان على نظامك الخارجي تضمين رؤوس معينة، مثل رأس X-Source-System مخصص للتوجيه أو التدقيق، فانقر + إضافة رأس (+ Add Header).

  2. أدخل اسم الرأس (Header name) في الحقل الأول وقيمة الرأس (Header value) في الثاني.

  3. أضف أي عدد مطلوب من الرؤوس. انقر علامة X الحمراء في صف لإزالته.

الخطوة 6 — تعريف الحمولة المتوقعة بمخطط JSON

يتيح لك حقل الحمولة المتوقعة (Expected Payload) وصف بيانات JSON التي سيرسلها النظام الخارجي. يصبح كل حقل في المستوى الأعلى تعرّفه متغيرًا لسير العمل تستطيع العُقد اللاحقة استخدامه.

  1. أدخل في منطقة نص الحمولة المتوقعة (مخطط JSON) كائن JSON يصف حقولك بالصورة الآتية:

    {
  "employee_id": "string",
  "department": "string",
  "request_type": "string",
  "amount": "number",
  "description": "string",
  "submission_date": "date"
}

    الأنواع المدعومة: string وnumber وboolean وdate وarray وobject.

  2. أثناء الكتابة، يكتشف الحقل المخطط وتظهر شارة تقول تم اكتشاف N من المتغيرات (N variables detected).

  3. انقر معاينة المتغيرات (Preview Variables) لعرض القائمة الكاملة لمتغيرات سير العمل التي سينشئها المخطط. تُسبق أسماء الحقول بـhttpstart_ لتكوين اسم المتغير:

    الحقل في الحمولة اسم متغير سير العمل
    employee_id {{httpstart_employee_id}}
    department {{httpstart_department}}
    amount {{httpstart_amount}}

  4. دوّن أسماء المتغيرات المولّدة؛ فستستخدمها في عُقد أخرى. على سبيل المثال:

    • في موضوع عقدة بريد: New request from {{httpstart_employee_id}}
    • في وصف عقدة مهمة: Amount: {{httpstart_amount}}
    • في شرط If/Else: httpstart_amount > 10000

الخطوة 7 — اختبار نقطة النهاية

  1. انقر زر الاختبار الآن (Test Now)، وهو الرابط الأخضر في قسم اختبار نقطة النهاية (Test Endpoint). يرسل المصمم طلب POST تجريبيًا إلى نقطة النهاية باستخدام مخطط الحمولة الذي عرّفته أو حمولة اختبار افتراضية.

  2. تظهر نافذة منبثقة تعرض النتيجة:

    • نجح الاختبار (Test Successful) — استجابة HTTP 200 مع النص، بما فيه معرّف المثيل الجديد. يؤكد ذلك أن نقطة النهاية تعمل وأن سير العمل جاهز.
    • فشل الاختبار (Test Failed) — رمز خطأ HTTP مع رسالة الخطأ. من الأسباب الشائعة أن سير العمل لم يُحفظ بعد، أو أن اسمه فارغ، أو أن حالته غير نشطة.

  3. إذا فشل الاختبار، فتحقق من: 1) حفظ سير العمل ووجود اسم له، و2) أن حالته نشط (Active) في شاشة إدارة سير العمل، و3) عدم وجود قيد شبكي يمنع استدعاءات API المحلية.

الخطوة 8 — حفظ العنوان ومشاركته

  1. انقر حفظ (Save) أسفل لوحة الإعدادات. تتحدث عقدة البداية في اللوحة لتعرض رمز كرة أرضية أخضر يشير إلى نشاط مُشغّل Webhook.

  2. شارك عنوان نقطة النهاية الكامل وتفاصيل المصادقة مع الفريق المسؤول عن النظام الخارجي، ليدمجها من جهته.

  3. بعد إعداد النظام الخارجي، اختبر تشغيلًا متكاملًا وتأكد من ظهور مثيل جديد في كل المثيلات.

استخدام بيانات Webhook في العُقد اللاحقة

بعد حفظ المُشغّل مع مخطط الحمولة، تتاح المتغيرات في سير العمل كاملًا. لاستخدامها:

  • في أي حقل نص، اكتب {{httpstart_ وستكمل لوحة المتغيرات الأسماء المتاحة تلقائيًا.
  • في لوحة المتغيرات (Variable Panel)، التي تفتح برمز المتغير في شريط أدوات المصمم، مرّر للعثور على جميع متغيرات httpstart_ المدرجة تحت عقدة البداية.
  • في عُقد الشرط (Condition) من نوع If/Else، استخدمها مباشرة في حقول التعبير، مثل: httpstart_amount أكبر من 10000.

استدعاء Webhook من أدوات شائعة

من cURL في سطر الأوامر

curl -X POST \
  "https://<workspace>.raptix.app/api/v1/dynamic-workflow/http-start/your-workflow-name" \
  -H "Content-Type: application/json" \
  -H "Authorization: ${RAPTIX_WEBHOOK_AUTH:?set the complete authorization value}" \
  -d '{"employee_id":"EMP-1042","department":"Engineering","amount":15000}'

من متصفح باستخدام JavaScript fetch

const response = await fetch(
  'https://<workspace>.raptix.app/api/v1/dynamic-workflow/http-start/your-workflow-name',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer your-token-here'
    },
    body: JSON.stringify({
      employee_id: 'EMP-1042',
      department: 'Engineering',
      amount: 15000
    })
  }
);
const result = await response.json();
console.log(result.instance_id); // The new workflow instance ID

من Postman

  1. أنشئ طلب POST جديدًا.
  2. اضبط URL على عنوان نقطة النهاية الكامل.
  3. أضف تحت Headers الرأس Content-Type: application/json وأي رأس مصادقة.
  4. الصق الحمولة تحت Body > raw > JSON.
  5. انقر Send. تؤكد استجابة 200 التي تتضمن instance_id نجاح العملية.

شرح الخيارات والإعدادات

الإعداد ما يفعله
الاسم (Name) تسمية العرض في عقدة البداية داخل اللوحة. القيمة الافتراضية: HTTP Request Start.
الوصف (Description) ملاحظة اختيارية تظهر في لوحة الخصائص.
الطريقة (Method) طريقة HTTP التي يجب على المستدعي استخدامها: GET أو POST أو PUT أو DELETE. يُنصح بـPOST.
المصادقة (Authentication) طريقة الأمان: None أو Bearer Token أو API Key أو Basic Auth.
نقطة النهاية (Endpoint) مسار URL مولّد تلقائيًا وللقراءة فقط، ويعتمد على اسم سير العمل. ينسخ زر النسخ العنوان الكامل.
الرؤوس (Headers) رؤوس مطلوبة اختيارية. يحتوي كل صف على حقل للاسم والقيمة. انقر + إضافة رأس للمزيد.
الحمولة المتوقعة (مخطط JSON) وصف JSON لحقول البيانات الواردة. تصبح أسماء الحقول متغيرات سير عمل مسبوقة بـhttpstart_.
معاينة المتغيرات (Preview Variables) زر لعرض قائمة متغيرات سير العمل المولّدة من مخطط الحمولة.
اختبار نقطة النهاية / الاختبار الآن يرسل طلب اختبار مباشرًا إلى نقطة النهاية ويعرض الاستجابة.

نصائح وأفضل الممارسات

  • استخدم أسماء حقول وصفية في مخطط الحمولة. يكون httpstart_vendor_invoice_number أوضح من httpstart_num عندما تستخدمه بعد عشر عُقد.
  • وثّق مخطط الحمولة خارج المنصة. شارك مخطط JSON مع الفريق الذي يبني التكامل الخارجي حتى يعرف بدقة ما ينبغي إرساله.
  • تحقق من اسم سير العمل قبل مشاركة العنوان. الاسم جزء من URL، وقد ينتج عن المحارف الخاصة ترميز URL غير متوقع. استخدم أسماء أبجدية رقمية بسيطة مع شرطات.
  • لا تترك المصادقة على None في بيئة الإنتاج على خادم متاح للعامة. استخدم Bearer Token على الأقل لمنع بدء سير العمل من جهات غير مخوّلة.
  • اختبر حمولة نموذجية قبل الإطلاق. استخدم زر الاختبار الآن في المصمم أو Postman للتأكد من وصول البيانات بصورة صحيحة وظهور المتغيرات الصحيحة في كل المثيلات.
  • أبقِ سير العمل نشطًا. يعيد استدعاء Webhook لسير عمل غير نشط خطأ. تحقق من الحالة النشطة في إدارة سير العمل قبل تسليم العنوان.
  • إذا كان لا بد من تغيير اسم سير العمل، فحدّث كل المستدعين في الوقت نفسه. لا توجد إعادة توجيه للعنوان، وتتوقف العناوين القديمة فورًا.

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

س: هل تتطلب نقطة نهاية Webhook حساب مستخدم لاستدعائها؟

لا. صُممت نقطة النهاية لتكون قابلة للاستدعاء العام حتى تستطيع الأنظمة الخارجية استخدامها من دون تسجيل الدخول. توفر المصادقة، مثل Bearer Token أو API Key أو Basic Auth، الأمان بدلًا من ذلك. استخدم المصادقة دائمًا لنقاط نهاية الإنتاج.

س: ما رموز حالة HTTP التي تعيدها نقطة النهاية؟

  • 200 OK — تم إنشاء مثيل سير العمل بنجاح. يحتوي النص على instance_id وstatus وworkflow_name.
  • 400 Bad Request — نص الطلب غير صالح أو الحقول المطلوبة مفقودة.
  • 404 Not Found — لا يوجد سير عمل نشط بهذا الاسم.
  • 405 Method Not Allowed — استُخدمت طريقة HTTP خاطئة.
  • 429 Too Many Requests — تم تجاوز حد معدل الطلبات.
  • 500 Internal Server Error — حدث خطأ من جهة الخادم.

س: كيف أتعامل مع إخفاق Webhook من جهة النظام المستدعي؟

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

س: هل يمكنني إرسال كائنات JSON متداخلة في الحمولة؟

نعم. تُحلل الكائنات المتداخلة في الحمولة وتتاح كمتغيرات سير عمل أيضًا. إذا عرّفت حقلًا من نوع object، فسيُحفظ كمتغير نص JSON. ويمكنك الإشارة إلى قيم متداخلة محددة باستخدام ترميز النقطة في عُقد الشروط، بحسب إمكانات منشئ التعبيرات.

س: ماذا لو احتجت إلى تمرير بيانات ثنائية، مثل الملفات؟

تقبل نقطة نهاية Webhook بيانات JSON فقط. لمسارات سير العمل المبنية على الملفات، استخدم نموذج التشغيل اليدوي (Trigger Manually) المنشور بحقوق ملفات، أو اجمع الملفات في عقدة مهمة لاحقة.

س: هل يمكن لأنظمة خارجية عدة استدعاء عنوان Webhook نفسه؟

نعم. ما دام كل مستدعٍ يستخدم العنوان وتنسيق الحمولة والمصادقة الصحيحة، ينشئ كل استدعاء مثيلًا مستقلًا. تنطبق حدود المعدل على جميع المستدعين.

س: هل تُسجّل بيانات الطلب الواردة في مكان ما لأغراض التدقيق؟

نعم. تحتوي علامة الإجراءات في قاعدة بيانات سير العمل على سجلات إجراءات سير العمل المحفوظة. وتسمح علامة التبويب الحالية أيضًا للمستخدمين المخوّلين بإضافة تلك السجلات أو تحريرها أو حذفها، لذلك استخدم عملية الاحتفاظ المعتمدة في مؤسستك عند الحاجة إلى دليل غير قابل للتغيير. وتتاح بيانات مثيل سير العمل أيضًا عبر عرض تفاصيل سير العمل.

أدلة ذات صلة

مُشغّلات البدايةتشغيل سير عملكل المثيلاتالمتغيرات وعلامات الدمجصلاحيات سير العملقاعدة بيانات سير العملمسرد مصطلحات RAPTIX
هل ما زلت بحاجة إلى مساعدة؟ راجع الحصول على مساعدة من الدعم أو تواصل مع مسؤول مساحة العمل.