تحتاج أحيانًا إلى بدء سير عمل فور وصول طلب من تطبيق خارجي، دون انتظار تشغيل يدوي أو فحص دوري. هنا تستخدم Webhook في n8n: رابط يستقبل الطلب والبيانات، ثم يبدأ تنفيذ العقد التالية.
سنستخدم مثالًا تعليميًا لطلب تجريبي يحتوي على رقم واسم منتج وكمية. لن نرسل بريدًا أو نسجل عملية بيع؛ الهدف هو فهم وصول JSON ومراجعة المخرجات قبل ربط بيانات حقيقية.
ما الذي تحتاج إليه؟
تحتاج إلى نسخة n8n تستطيع الوصول إليها، وصلاحية إنشاء سير عمل، وأداة إرسال طلبات مثل HTTP Request في سير آخر أو curl على جهازك. إذا كان n8n محليًا، فإن localhost في جهاز الخدمة الخارجية لا يشير إلى جهازك. يلزم عنوان يمكن للخدمة الوصول إليه واتصال HTTPS مناسب قبل استخدامه للإنتاج.
إذا لم تبنِ سير عمل من قبل، ابدأ بـدليل n8n للمبتدئين.
1. أنشئ عقدة الاستقبال
- أنشئ سير عمل جديدًا وأضف عقدة Webhook.
- اختر HTTP Method بقيمة POST لاستقبال بيانات المثال.
- اختر مسارًا مثل demo-order، وتأكد أنه غير مستخدم بالطريقة نفسها في سير آخر.
- اختر Respond بقيمة Immediately في التجربة الأولى، لتفصل استقبال الطلب عن العمليات اللاحقة.
- افتح Test URL وانسخ الرابط الذي تعرضه نسختك؛ لا تركب الرابط من الذاكرة.
2. أرسل بيانات اختبار
اضغط Listen for test event، ثم أرسل الطلب قبل انتهاء فترة الاستماع. وفق توثيق n8n الحالي، يستمر رابط الاختبار في الاستماع لمدة 120 ثانية. المثال التالي مناسب للطرفيات التي تدعم اقتباس shell؛ يمكن إرسال JSON نفسه من أداة طلبات بواجهة رسومية.
curl --request POST 'https://YOUR-N8N-HOST/webhook-test/demo-order' --header 'Content-Type: application/json' --data '{"order_id":"DEMO-101","product":"Notebook","quantity":2}'استبدل العنوان بالرابط الذي نسخته. استخدم بيانات وهمية، ولا تضع مفاتيح خدمة أو بيانات عميل في مثال قابل للنشر. عند نجاح الاستقبال، افتح مخرجات Webhook وابحث عن الحقول داخل body. وجود رد نجاح للاستقبال لا يثبت أن أي مهمة لاحقة اكتملت.
3. افحص الحقول قبل استخدامها
أضف Edit Fields بعد Webhook وأنشئ حقلًا باسم order_id باستخدام التعبير {{ $json.body.order_id }}. اقرأ مخرجات عقدتك قبل اعتماد المسار؛ فقد يختلف شكل البيانات عندما يرسل التطبيق Form Data بدل JSON.
أضف فحصًا للكمية ورقم الطلب قبل أي إجراء خارجي. في المثال، يمكنك التأكد من أن الكمية رقم موجب وأن رقم الطلب غير فارغ. طلب ناقص لا ينبغي أن ينتقل مباشرة إلى تسجيل عملية أو إرسال رسالة. راجع دليل فهم البيانات في n8n لتتبع القيم بين العقد.
4. انتقل من الاختبار إلى الإنتاج
Test URL مخصص للتطوير وعرض البيانات داخل المحرر. Production URL يعمل بعد حفظ ونشر سير العمل وفق الواجهة الحالية؛ قد تعرض نسخ أقدم التفعيل باسم Active. ضع رابط الإنتاج في الخدمة المرسلة، ثم أرسل طلبًا تجريبيًا جديدًا وراجع تبويب Executions. بيانات تشغيل الإنتاج لا تظهر تلقائيًا في لوحة المحرر مثل الاختبار.
احتفظ بسجل الاختبار: وقت الإرسال، رقم الطلب، رمز الاستجابة ونتيجة التنفيذ. بهذه الطريقة تعرف هل المشكلة في الإرسال، الاستقبال، أم عقدة لاحقة.
أخطاء شائعة وما الذي تراجعه
- الرابط يعمل أثناء الاختبار ثم يتوقف: تحقق من أنك لم تضع Test URL في الخدمة الدائمة.
- طلب POST لا يصل: طابق طريقة الإرسال مع HTTP Method والمسار الفعلي.
- لا يظهر التنفيذ في المحرر: افتح Executions عند استخدام رابط الإنتاج.
- مسار مستخدم: لا تسجل Webhook آخر بالمسار وطريقة HTTP نفسيهما؛ اختر مسارًا مختلفًا.
- JSON غير واضح: راجع Content-Type ومحتوى الطلب، ثم مخرجات العقدة بدل تخمين أسماء الحقول.
حماية الرابط ومنع تكرار العملية
يدعم Webhook المصادقة باستخدام Basic أو Header أو JWT. اختر ما تدعمه الخدمة المرسلة وخزن الأسرار في Credentials. لا تضع سر Header داخل JavaScript عام على موقعك؛ يستطيع الزائر الاطلاع عليه. تقييد CORS وحده لا يحل محل المصادقة.
قد تعيد الخدمة إرسال الحدث إذا لم تحصل على الرد المتوقع. قبل تنفيذ إجراء مثل إرسال تأكيد أو إضافة طلب، تحقق من رقم حدث أو رقم طلب سبق معالجته في مخزن مناسب. الاختبار برقم DEMO-101 مرتين يساعدك على التفكير في هذا السلوك، لكنه لا ينشئ آلية منع التكرار تلقائيًا.
أسئلة متكررة
هل Webhook بديل لعقدة التطبيق؟
يفيد عندما ترسل الخدمة أحداثًا ولا توجد عقدة مشغل مناسبة. إن وجدت عقدة تلبي المهمة فقد تكون أسهل في الإعداد.
هل يكفي رد الاستقبال لتأكيد الطلب للعميل؟
لا. اختر توقيت الرد بما يناسب العملية، وافصل رسالة «وصل الطلب» عن «تمت معالجته».
المصادر
مراجعة المعلومات: 6 أكتوبر 2026. المثال تعليمي؛ راجع إعدادات نسختك قبل تشغيل مهام فعلية.