تكامل Webhook وAPI في n8n: دليل HTTP Node
n8n webhook API تحوّل نقطة Webhook Trigger في n8n طلبات HTTP الواردة إلى تنفيذ لسير العمل، بينما تستدعي HTTP Request Node أي REST API من داخل سير العمل. يوفر هذا الثنائي معاً الطريقة الأكثر مرونة لدمج الخدمات التي لا تمتلك موصلاً أصلياً في n8n.
Webhook وHTTP Node في n8n: الفرق بين المشغّل والطلب
نقطة Webhook Trigger هي عنوان URL يفتحه n8n للعالم الخارجي؛ تُشغّل طلبات HTTP الواردة إلى هذا العنوان سير العمل. أما HTTP Request Node فترسل طلبات من داخل سير العمل إلى خدمات خارجية. إحداهما تلتقط حركة البيانات الواردة والأخرى تُنتج طلبات صادرة.
إن فهم الفرق بين نقطتَي HTTP في n8n هو أساس بناء معمارية التكامل الصحيحة. محرك سير عمل n8n يستقبل الأحداث عبر نقاط المشغّل ويعالجها عبر نقاط متتالية. Webhook Trigger هو الأكثر مرونة بين هذه المشغّلات: يوفر n8n عنوان URL فريداً، وأي طلب HTTP إليه — GET أو POST أو PUT أو PATCH أو DELETE — يُنفّذ سير العمل على الفور.
تؤدي HTTP Request Node دوراً مختلفاً. خلال تشغيل سير العمل، ترسل طلباً إلى أي API خارجي تحدده وتمرر الاستجابة إلى النقاط اللاحقة. يمكنك استخدامها للاتصال بنظام CRM أو ERP أو أي منصة SaaS. وكل خدمة تتواصل عبر HTTP يمكن تضمينها في سير العمل من خلال هذه النقطة، بغض النظر عن وجود موصل أصلي لها في n8n.
| الخاصية | Webhook Trigger Node | HTTP Request Node |
|---|---|---|
| الدور | التقاط الطلبات الواردة (مستمع سلبي) | إرسال طلبات صادرة (استدعاء نشط) |
| الموضع | بداية سير العمل (مشغّل) | أي مكان داخل سير العمل |
| الاتجاه | من الخارج إلى n8n | من n8n إلى الخارج |
| الاستخدام النموذجي | نشر webhook endpoint | استدعاء REST API |
| المصادقة | Header Auth, Basic Auth, JWT (اختياري) | مفتاح API, OAuth2, Header Auth, Basic Auth |
إعداد Webhook Trigger: عنوان URL وطريقة HTTP والمصادقة
بعد إضافة نقطة Webhook Trigger، يوفر n8n عنوانَي URL: أحدهما للاختبار والآخر للإنتاج. يتم تهيئة طريقة HTTP ووضع الاستجابة والمصادقة الاختيارية مباشرةً من لوحة النقطة.
عند إضافة نقطة Webhook Trigger، يُنشئ n8n تلقائياً مساراً فريداً يمكنك تخصيصه — مثلاً منحه اسماً ذا معنى كـ `/webhook/tsjil-amiyl`. يعرض n8n عنوان URL الاختباري (`/webhook-test/...`) وعنوان URL الإنتاجي (`/webhook/...`) بشكل منفصل. يكون عنوان URL الاختباري نشطاً فقط عند تشغيل سير العمل يدوياً؛ أما عنوان URL الإنتاجي فيكون نشطاً طالما سير العمل مفعّل.
يُعدّ ترك طريقة HTTP كـ POST مناسباً لمعظم السيناريوهات، غير أن GET وPUT وPATCH وDELETE متاحة أيضاً. وضع الاستجابة قرار مهم: يعيد 'Immediately' رمز 200 OK فور استلام الطلب بينما يستمر سير العمل في الخلفية. أما 'When Last Node Finishes' فينتظر اكتمال سير العمل بالكامل ويعيد مخرجات النقطة الأخيرة كجسم للاستجابة — يُفضَّل هذا الوضع لسيناريوهات بوابة API المتزامنة.
- المسار: مسار URL مخصص اختياري (مثل /webhook/orders)
- طريقة HTTP: GET أو POST أو PUT أو PATCH أو DELETE أو ANY
- وضع الاستجابة: Immediately أو When Last Node Finishes
- بيانات الاستجابة: Last Node أو No Data
- المصادقة: None أو Basic Auth أو Header Auth
عند تفعيل المصادقة، تُشغّل سير العمل فقط الطلبات التي تحمل بيانات اعتماد صحيحة؛ وتُرفض الطلبات غير الموثقة بالرمز 401. يحمي ذلك webhook endpoint الخاص بك من الاستدعاءات غير المصرح بها ويساعد على تلبية متطلبات الأمان المؤسسية. لمزيد من التفاصيل حول تهيئة الأمان المؤسسي، راجع دليل أمان وحوكمة n8n المؤسسية.
استدعاء أي API باستخدام HTTP Request Node
تتيح HTTP Request Node تهيئة عنوان URL وطريقة HTTP والترويسات ومعلمات الاستعلام وجسم الطلب والمصادقة في واجهة واحدة. يمكنك الاتصال بأي REST API داخلي أو خارجي من خلال هذه النقطة.
تُعدّ لوحة تهيئة HTTP Request Node واجهة HTTP client كاملة. يمكنك اختيار GET أو POST أو PUT أو PATCH أو DELETE أو HEAD من حقل Method. في حقل URL يمكنك إدخال عنوان ثابت أو بناء عنوان URL ديناميكي باستخدام تعبيرات n8n من مخرجات النقاط السابقة — فمثلاً `https://api.example.com/users/{{ $json.userId }}` يجلب ملف تعريف مختلف في كل تشغيل.
تُدار الترويسات ومعلمات الاستعلام وجسم الطلب في علامات تبويب منفصلة. لإرسال جسم JSON اختر 'JSON' كنوع للجسم وأدخل أزواج المفتاح-القيمة أو اكتب تعبير JSON مباشرةً. انتقل إلى وضع 'Form Data' لإرسال بيانات النموذج. الوضع 'Binary' متاح لتحميل الملفات والبيانات الثنائية الأخرى.
| المعلمة | الخيارات / الملاحظات | الاستخدام النموذجي |
|---|---|---|
| Method | GET, POST, PUT, PATCH, DELETE, HEAD | عمليات CRUD |
| URL | ثابت أو ديناميكي عبر التعبيرات | نقطة نهاية المورد |
| Headers | أزواج مفتاح-قيمة، تدعم التعبيرات | Content-Type, Accept, ترويسات مخصصة |
| Query Params | أزواج مفتاح-قيمة | التصفية والترقيم |
| Body Type | JSON, Form Data, Raw, Binary | إرسال البيانات |
| Authentication | None، Credential (مهيأ مسبقاً) | أمان API |
| Timeout | بالميلي ثانية | استجابات API طويلة الأمد |
| Retry On Fail | تشغيل/إيقاف، عدد المحاولات | التعافي من الأخطاء العابرة |
يفتح تفعيل 'Send Query Parameters' و'Send Headers' حقولاً إضافية. نظراً لدعمها التعبيرات، يمكنك استخدام القيم الديناميكية من النقاط السابقة مباشرةً. على سبيل المثال، يمكنك التكرار على قائمة سجلات مُرجعة من استعلام قاعدة بيانات وإجراء استدعاء API منفصل لكل سجل — مع إدارة معدل النقل بواسطة SplitInBatches للالتزام بحدود rate limit.
المصادقة وبيانات الاعتماد: مفتاح API وOAuth2 وHeader Auth
يخزّن n8n بيانات الاعتماد بصورة مشفرة ويتيح إعادة استخدام كائنات Credential في سير عمل متعددة. الأنواع المدعومة: مفتاح API وHeader Auth وBasic Auth وOAuth2 (تدفقا Authorization Code وClient Credentials).
في n8n، تُخزَّن بيانات الاعتماد في مدير Credentials مركزي. يحفظ كل Credential في قاعدة بيانات مشفرة وتستدعيه سير العمل كمرجع — ولا يُضمَّن مباشرةً في تهيئة النقطة. هذا يمثل ميزة من حيث الأمان والصيانة على حدٍّ سواء: عند تغيير مفتاح API تُحدّثه في مكان واحد، وتتحدث تلقائياً جميع سير العمل التي تستخدم هذا المفتاح.
| نوع المصادقة | حالة الاستخدام | إعدادات n8n |
|---|---|---|
| مفتاح API | مفتاح ثابت كترويسة أو معلمة استعلام | اسم المفتاح وقيمته؛ موضع 'Header' أو 'Query' |
| Header Auth | المصادقة عبر اسم وقيمة ترويسة مخصصة | اسم الترويسة وقيمتها (مثل X-API-Token) |
| Basic Auth | HTTP Basic باسم مستخدم وكلمة مرور | حقلا Username وPassword |
| OAuth2 (Auth Code) | وصول معتمد من المستخدم (خدمات طرف ثالث) | Client ID, Secret, Auth/Token URL, Scope |
| OAuth2 (Client Credentials) | وصول خادم-لخادم (M2M) | Client ID, Secret, Token URL |
يُعدّ دعم OAuth2 من أقوى ميزات n8n. في تدفق Authorization Code، يدير n8n إعادة توجيه التخويل عبر المتصفح؛ وعند انتهاء صلاحية access token يستخدم n8n refresh token تلقائياً للحصول على رمز جديد في الخلفية. يتيح ذلك دمج الخدمات المؤسسية القائمة على OAuth2 — كـ Google Workspace وMicrosoft 365 وSalesforce — في سير العمل دون إدارة يدوية للرموز. للتوافق مع سياسات الأمان المؤسسية، نوصي بمراجعة دليل أمان وحوكمة n8n.
عند إنشاء Credential، يتحقق زر 'Test Credential' من صحته قبل الحفظ. تكتشف هذه الميزة الأخطاء في التهيئة مبكراً وتمنع إضاعة الوقت خلال اختبار سير العمل.
تحويل البيانات: JSON والتعبيرات وCode Node
لتحويل استجابات API إلى بيانات سير العمل، استخدم تعبيرات n8n (صيغة الأقواس المزدوجة) أو Code Node (JavaScript أو Python). تتولى التعبيرات تعيين الحقول البسيطة، بينما تتعامل Code Node مع منطق التحويل المعقد.
تُمرَّر استجابة JSON التي تعيدها HTTP Request Node تلقائياً إلى النقاط اللاحقة. يتيح محرك التعبيرات في n8n الوصول إلى هياكل JSON المتداخلة بعمق باستخدام الترقيم النقطي وفهرسة المصفوفات — مثلاً `{{ $json.data.items[0].name }}`. تقرأ من مخرجات النقطة الحالية عبر `$json`، وتصل إلى جميع العناصر عبر `$items()`، وتستخدم متغيرات سير العمل عبر `$vars`.
للتحويلات المعقدة للبيانات، تُعدّ Code Node (المعروفة سابقاً بـ Function Node) الخيار المفضل. توفر بيئة تشغيل كاملة بـ JavaScript أو Python: صفّف المصفوفات، وأعد تشكيل الكائنات، وحوّل تنسيقات التواريخ، أو ادمج البيانات من مصادر متعددة. Code Node بديل قوي في كل موقف لا يكفي فيه محرك التعبيرات الافتراضي في n8n.
- {{ $json.fieldName }} — قراءة حقل من العنصر الحالي
- {{ $json.nested.object.value }} — الوصول إلى JSON المتداخل
- {{ $items('NodeName')[0].json.field }} — الحصول على مخرجات نقطة محددة
- {{ $now.format('YYYY-MM-DD') }} — تعبيرات التاريخ والوقت
- Code Node: return items.map(item => ({ json: { id: item.json.id, name: item.json.name } })) — تحويل العناصر
عند العمل مع مجموعات بيانات كبيرة، استخدم SplitInBatches لمعالجة البيانات على دفعات؛ نفّذ استدعاء HTTP Request لكل دفعة لتحسين استخدام الذاكرة والالتزام بحدود rate limit الخاصة بـ API. لتعيين البيانات الذكي والتحويلات المدعومة بالذكاء الاصطناعي، راجع دليل إعداد وكيل الذكاء الاصطناعي في n8n.
معالجة الأخطاء وإعادة المحاولة: Retry On Fail وError Workflow
يُعيد خيار 'Retry On Fail' في HTTP Request Node المحاولة تلقائياً عند الأخطاء الشبكية العابرة أو استجابات 5xx. بالنسبة لسير العمل الحيوية، يُؤتمت Error Workflow المخصص إشعارات الأخطاء والإجراءات التعويضية.
في بيئة الإنتاج، تواجه تكاملات API حتماً أخطاءً عابرة: انتهاء مهلة الشبكة، وتحديد معدل الطلبات (429)، أو أعطال الخادم المؤقتة (503). يوفر n8n خيار 'Retry On Fail' على مستوى HTTP Request Node. عند تفعيله، تحدد الحد الأقصى لعدد المحاولات ووقت الانتظار بين المحاولات (بالميلي ثانية). يمكن محاكاة التراجع الأسي (exponential backoff) بإضافة Wait Node بين المحاولات.
إلى جانب معالجة الأخطاء على مستوى النقطة، يوفر n8n أيضاً إدارة الأخطاء على مستوى سير العمل. يمكنك تعريف 'Error Workflow' لكل سير عمل؛ وعند حدوث خطأ غير معالج في سير العمل الرئيسي، يُشغَّل هذا سير العمل المخصص تلقائياً. يستقبل Error Workflow رسالة الخطأ والسياق عبر `$execution.error`، مما يتيح أتمتة الإجراءات التعويضية: إرسال إشعار إلى Slack، أو كتابة السجل الفاشل إلى قاعدة بيانات، أو إرسال بريد إلكتروني إلى المسؤول.
- HTTP Request Node > Settings > Retry On Fail: مفعّل
- Max Tries: 3-5 (5 للتكاملات الحيوية)
- Wait Between Tries: 1000-5000 مللي ثانية (وفقاً لـ rate limit الخاص بـ API)
- Settings > On Error: قيّم 'Continue' مقابل 'Stop And Error'
- مستوى سير العمل: Settings > Error Workflow — اربط سير عمل معالج الأخطاء
- داخل Error Workflow: نقطة إشعار (Slack أو بريد إلكتروني) + نقطة تسجيل (قاعدة بيانات أو ملف سجل)
تُعدّ إدارة rate limit حيوية بشكل خاص في العمليات الجماعية. تجاوز عدد الطلبات المسموح بها في الثانية أو الدقيقة يؤدي إلى خطأ 429. لمنع ذلك، قيّد حجم الدفعة باستخدام SplitInBatches وأضف Wait Node بين الدفعات، لتشغيل سيناريوهات معالجة البيانات بالحجم الكبير بأمان ضمن حدود API.
مثال عملي: تكامل API مخصص خطوة بخطوة
لتكامل API مخصص أو مغلق مع n8n: استقبل البيانات بـ Webhook Trigger، واستدعِ API بـ HTTP Request Node، وحوّل الاستجابة بـ Code Node، وأضف معالجة الأخطاء. ينطبق هذا النمط على أي خدمة بدون موصل أصلي.
لنستعرض سيناريو واقعياً: نظام ERP داخلي يستدعي webhook خاصاً بـ n8n عند إنشاء طلب جديد. يلتقط سير العمل هذا الحدث، ويحيل تفاصيل الطلب إلى API خارجي للوجستيات، ويسترجع رقم التتبع من الاستجابة، ويرسله إلى نظام إشعارات العملاء. لا تمتلك أي من هذه الخدمات الثلاث موصلاً أصلياً في n8n — غير أن جميعها تتواصل عبر HTTP.
- Webhook Trigger: يستقبل طلب POST من ERP (JSON الطلب). المسار: /webhook/new-order. المصادقة: Header Auth (X-ERP-Secret).
- HTTP Request (API اللوجستيات): POST https://api.logistics.example.com/v1/shipments. الجسم: JSON مبني من بيانات الطلب. Auth: مفتاح API (Header: Authorization: Bearer {{credential}}). Retry On Fail: مفعّل، Max 3.
- Code Node: يستخرج tracking_number وestimated_delivery من استجابة API اللوجستيات؛ يجمعه مع بريد العميل الإلكتروني لبناء payload الإشعار.
- HTTP Request (API الإشعارات): POST https://api.notification.example.com/send. الجسم: payload من Code Node. Auth: Basic Auth.
- Error Workflow: في حال فشل أي خطوة، يُرسَل إشعار إلى Slack ويُسجَّل معرّف الطلب الفاشل في قاعدة البيانات.
يغطي هذا النمط الغالبية العظمى من سيناريوهات الأتمتة المؤسسية. للحالات الأكثر تعقيداً — تفويض OAuth2 متعدد الخطوات، وAPIs غير المتزامنة، والمعماريات الهجينة التي تجمع webhook والاستطلاع — راجع دليل حالات استخدام n8n المؤسسية. إذا أردت إضافة قدرات الذكاء الاصطناعي إلى تكاملاتك، يوفر دليل إعداد وكيل الذكاء الاصطناعي في n8n نقطة انطلاق شاملة.
تُمكّن مرونة n8n من تضمين أي نظام يتواصل عبر HTTP — سواء أكان SaaS سحابياً أم نظاماً قديماً داخلياً أم جهاز IoT — في سير العمل. تضمن إدارة بيانات الاعتماد المشفرة والتحكم في الوصول المستند إلى الأدوار وسجلات التدقيق تلبية متطلبات الأمان المؤسسية.
الأسئلة الشائعة
ما هو Webhook وكيف يعمل في n8n؟
Webhook هو آلية ترسل فيها تطبيقات طلب HTTP إلى عنوان URL آخر عند وقوع حدث معين. في n8n، توفر نقطة Webhook Trigger عنوان URL يستمع لهذه الطلبات؛ وكل طلب وارد يشغّل سير العمل تلقائياً.
ما الذي تفعله HTTP Request Node وما APIs المتوافقة معها؟
ترسل HTTP Request Node طلباً من سير عمل n8n إلى أي HTTP/HTTPS endpoint. تعمل مع أي خدمة تدعم معيار REST API، وهي الطريقة الأساسية للتكامل مع APIs المخصصة أو المؤسسية أو المغلقة التي لا تمتلك موصلاً أصلياً في n8n.
كيف تتم مصادقة API في n8n؟
يُنشأ كائن Credential في مدير Credentials باختيار أحد الأنواع المدعومة: مفتاح API أو Header Auth أو Basic Auth أو OAuth2. يُختار هذا Credential في HTTP Request Node ويُطبَّق تلقائياً على جميع الطلبات، وتُخزَّن بيانات الاعتماد بصورة مشفرة.
هل يدعم n8n OAuth2؟ هل تجديد الرمز المميز تلقائي؟
نعم، يدعم n8n OAuth2 بتدفقَي Authorization Code وClient Credentials. عند انتهاء صلاحية access token، يستخدم n8n refresh token تلقائياً في الخلفية للحصول على رمز جديد؛ ويستمر سير العمل دون انقطاع وبدون أي تدخل يدوي.
كيف أدير حدود rate limit الخاصة بـ API في n8n؟
استخدم SplitInBatches لتقسيم الطلبات الجماعية إلى دفعات، وأضف Wait Node بين الدفعات للالتزام بالمعدل المسموح للـ API. يُعيد خيار Retry On Fail في HTTP Request Node المحاولة تلقائياً عند أخطاء 429.
كيف تعمل معالجة الأخطاء في HTTP Request Node بـ n8n؟
يمكن تفعيل Retry On Fail على مستوى النقطة. على مستوى سير العمل، عرّف Error Workflow للتعامل مع الأخطاء غير المعالجة — إرسال إشعارات Slack، وتسجيل السجلات الفاشلة في قاعدة البيانات، أو تشغيل الإجراءات التعويضية تلقائياً.
هل يمكنني تكامل API داخلي أو مغلق مع n8n؟
نعم. تعمل HTTP Request Node مع أي API يمكن الوصول إليه عبر عنوان URL. في نشر n8n المستضاف ذاتياً، عند تثبيته على خادم لديه وصول إلى الشبكة الداخلية، يمكنه أيضاً الاتصال بـ APIs الخاصة خلف VPN أو جدار الحماية.
هل يمكنني استخدام Webhook وHTTP Request Node في سير عمل واحد؟
نعم، وهذا نمط شائع. يستقبل Webhook Trigger البيانات من الخارج، وترسل HTTP Request Node واحدة أو أكثر داخل سير العمل طلبات إلى APIs مختلفة. يتيح ذلك تنسيق تكاملات متعددة الأنظمة في سير عمل واحد.
الخلاصة
يُمكّن Webhook Trigger وHTTP Request Node في n8n معاً من تضمين أي خدمة قائمة على HTTP في سير عمل. بالنسبة للـ APIs المخصصة والمؤسسية والمغلقة التي لا تمتلك موصلات أصلية، توفر هاتان النقطتان أساساً مرناً وآمناً للتكامل. تلبي إدارة بيانات الاعتماد المشفرة ودعم OAuth2 وتجديد الرمز المميز التلقائي المتطلبات الأمنية المؤسسية وتعزز إنتاجية المطورين في آنٍ واحد.
تجعل منطق إعادة المحاولة ومعالجة الأخطاء وError Workflow تكاملاتك جاهزةً للإنتاج. للحصول على سيناريوهات تكامل خاصة بقطاعك وتهيئة بنية n8n على النطاق المؤسسي، تواصل مع فريق تكامل Sora لجلسة اكتشاف مجانية.