استخدام Webhooks وبيانات الاعتماد في n8n: الروابط العامة وروابط إعادة توجيه OAuth والاختبار

يُنشئ n8n جميع روابط Webhook وروابط OAuth callback اعتمادًا على متغير البيئة WEBHOOK_URL. اضبطه على عنوان HTTPS العام الخاص بك، مثل https://n8n.example.com/. روابط الاختبار (/webhook-test/...) لا تعمل إلا أثناء استماع المحرر. أما روابط الإنتاج (/webhook/...) فلا تعمل إلا بعد تفعيل سير العمل. ويجب أن تُدرج تطبيقات OAuth2 لدى Google أو Microsoft أو Slack الرابط https://n8n.example.com/rest/oauth2-credential/callback باعتباره redirect URI.

يشرح هذا الدليل كيفية جعل Webhooks قابلة للوصول، وكيفية تأمينها، وكيف يخزّن n8n بيانات الاعتماد، وكيفية اختبار كل ذلك باستخدام curl. ينطبق هذا الدليل على استضافة n8n من Cloudesta وعلى أي نسخة n8n مستضافة ذاتيًا تعمل داخل Docker على Ubuntu 22.04 أو 24.04.

المتطلبات المسبقة

• نسخة n8n تعمل داخل Docker باستخدام Docker Compose، مع صلاحية وصول SSH بحساب root إلى السيرفر.
• نطاق أو نطاق فرعي، مثل n8n.example.com، مع إمكانية تعديل إعدادات DNS الخاصة به.
• بروكسي عكسي أمام n8n يتولى إنهاء اتصالات HTTPS. تستخدم الأمثلة التالية Nginx.
• أداة curl على جهازك أو على السيرفر.

1. كيف يُنشئ n8n روابط Webhook؟

لكل عقدة Webhook مسار، مثل order-created. يدمج n8n هذا المسار مع WEBHOOK_URL لينتج رابطين:

• رابط الاختبار: https://n8n.example.com/webhook-test/order-created. لا يعمل هذا الرابط إلا بعد النقر على Listen for test event أو Execute workflow في المحرر. يستقبل طلبًا واحدًا فقط ثم يتوقف عن الاستماع، كما تنتهي مهلته بعد دقيقتين تقريبًا. استخدمه أثناء بناء سير العمل.
• رابط الإنتاج: https://n8n.example.com/webhook/order-created. لا يعمل هذا الرابط إلا أثناء تفعيل سير العمل (ويحمل اسم Publish في إصدارات n8n الأحدث). تُنفَّذ العمليات في الخلفية وتظهر ضمن Executions.

إذا لم يكن WEBHOOK_URL مضبوطًا، يعرض n8n روابط مثل http://localhost:5678/webhook/...، وهي عناوين عديمة الفائدة للخدمات الخارجية. لإصلاح ذلك، افتح المجلد الذي يحتوي على ملف docker-compose.yml. إذا لم تكن تعرف مكانه، فابحث عنه بهذه الطريقة:

docker ps --format '{{.Names}}'
docker inspect <container-name> --format '{{ index .Config.Labels "com.docker.compose.project.working_dir" }}'

أضف هذه المتغيرات أو عدّلها في قسم environment: الخاص بخدمة n8n:

    environment:
      - N8N_HOST=n8n.example.com
      - N8N_PROTOCOL=https
      - WEBHOOK_URL=https://n8n.example.com/
      - N8N_EDITOR_BASE_URL=https://n8n.example.com/
      - N8N_PROXY_HOPS=1
      - N8N_PAYLOAD_SIZE_MAX=32

إليك وظيفة المتغيرات الأقل وضوحًا:

• N8N_PROXY_HOPS=1 يوجّه n8n إلى الوثوق بترويسات X-Forwarded-* القادمة من بروكسي عكسي واحد.
• N8N_PAYLOAD_SIZE_MAX هو الحد الأقصى لحجم جسم الطلب بوحدة MiB. القيمة الافتراضية 16.

طبّق التغييرات بإعادة إنشاء الحاوية، فالأمر restart وحده لا يعيد تحميل متغيرات البيئة.

cd /path/to/compose-folder
docker compose up -d
docker compose exec n8n printenv WEBHOOK_URL

استبدل n8n باسم خدمتك إذا كان مختلفًا.

2. كيف أجعل Webhook في n8n قابلًا للوصول من الإنترنت؟

DNS وHTTPS

أنشئ سجل A يوجّه n8n.example.com إلى عنوان IP الخاص بالسيرفر، مثل 203.0.113.10. بعد أن يبدأ النطاق في الاستجابة، أصدر الشهادة:

dig +short n8n.example.com
sudo apt update && sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d n8n.example.com

الجدار الناري

افتح منافذ SSH وHTTP وHTTPS فقط:

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

مهلات البروكسي وحجم جسم الطلب

يحتوي Nginx على إعدادين افتراضيين يعطّلان Webhooks:

• يرفض أجسام الطلبات التي يتجاوز حجمها 1 MB ويعيد الخطأ 413.
• يتخلى عن الاستجابات البطيئة بعد 60 ثانية.

في ملف الموقع الخاص بك، مثل /etc/nginx/sites-available/n8n.example.com، استخدم إعدادات مشابهة لما يلي داخل كتلة server التي تستمع على المنفذ 443:

    client_max_body_size 32m;

    location / {
        proxy_pass http://127.0.0.1:5678;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
    }

sudo nginx -t && sudo systemctl reload nginx

احرص على أن تتوافق قيمة client_max_body_size مع قيمة N8N_PAYLOAD_SIZE_MAX.

3. كيف أعيد استجابة مخصصة باستخدام Respond to Webhook؟

يتحكم إعداد Respond في عقدة Webhook في ما يتلقاه الطرف المُرسِل:

• Immediately: يعيد الاستجابة فورًا بينما يستمر سير العمل في الخلفية. هذا الخيار هو الأنسب للجهات المُرسِلة ذات المهلات القصيرة؛ فمثلًا يتوقع Slack ردًا خلال 3 ثوانٍ.
• When Last Node Finishes: يعيد مخرجات العقدة الأخيرة.
• Using 'Respond to Webhook' Node: تضع عقدة Respond to Webhook في أي موضع تريده داخل سير العمل، وتختار ما تعيده (JSON، أو نص، أو بيانات ثنائية، أو إعادة توجيه، أو العنصر الوارد الأول أو جميع العناصر الواردة، أو بلا بيانات)، بالإضافة إلى رمز الاستجابة وأي ترويسات. على سبيل المثال، يمكنك إعادة {"status":"received","id":"{{ $json.order_id }}"} مع الرمز 200، وإرسال الرمز 400 من فرع آخر عند فشل التحقق من صحة البيانات.

4. كيف أؤمّن Webhook في n8n؟

في عقدة Webhook، اضبط Authentication على Header Auth أو Basic Auth وأنشئ بيانات اعتماد لها:

• Header Auth: مثلًا، الاسم X-Webhook-Token مع قيمة عشوائية طويلة. أنشئ القيمة باستخدام openssl rand -hex 32. الطلبات التي لا تحتوي على الترويسة المطابقة تتلقى الخطأ 403.
• Basic Auth: اسم مستخدم وكلمة مرور يجب على الطرف المُرسِل تقديمهما.

إذا كانت الجهة المُرسِلة تنشر نطاقات عناوين IP الخاصة بها، يمكنك أيضًا تقييد مسار Webhook بعينه على مستوى البروكسي. أضف ما يلي فوق الكتلة العامة location /:

    location = /webhook/erp-sync {
        allow 198.51.100.0/24;
        deny all;
        proxy_pass http://127.0.0.1:5678;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

بالنسبة للخدمات التي توقّع البيانات المرسلة، مثل Stripe أو GitHub، تحقّق أيضًا من ترويسة التوقيع داخل سير العمل.

5. أين يخزّن n8n بيانات الاعتماد وكيف تُشفَّر؟

يخزّن n8n بيانات الاعتماد في قاعدة بياناته، وهي افتراضيًا SQLite داخل وحدة التخزين /home/node/.n8n، أو PostgreSQL إذا قمت بإعدادها. تُشفَّر بيانات الاعتماد بمفتاح تشفير يأتي من أحد مصدرين:

• متغير البيئة N8N_ENCRYPTION_KEY، إذا قمت بضبطه.
• وإلا، فمفتاح يُنشأ عند التشغيل الأول ويُحفظ في /home/node/.n8n/config.

لعرض المفتاح المخزّن:

docker compose exec n8n cat /home/node/.n8n/config

6. ما رابط إعادة توجيه OAuth الذي يجب استخدامه مع Google وMicrosoft وSlack؟

عند إنشاء بيانات اعتماد OAuth2، يعرض n8n رابطًا باسم OAuth Redirect URL. مع الإعدادات السابقة، يكون الرابط:

https://n8n.example.com/rest/oauth2-credential/callback

الصقه كما هو تمامًا في إعدادات التطبيق لدى مزوّد الخدمة:

• Google: Google Cloud Console ← APIs & Services ← Credentials ← OAuth client ID الخاص بك (من النوع Web application) ← Authorized redirect URIs. فعّل أيضًا واجهات API التي تحتاجها، مثل Gmail أو Sheets.
• Microsoft: Microsoft Entra admin center ← App registrations ← تطبيقك ← Authentication ← Add a platform ← Web ← Redirect URIs.
• Slack: api.slack.com/apps ← تطبيقك ← OAuth & Permissions ← Redirect URLs.

انسخ client ID وsecret إلى n8n، ثم انقر على Connect.

حسابات الخدمة ومفاتيح API

في حالة الوصول من سيرفر إلى سيرفر، لا تُستخدم روابط إعادة توجيه OAuth:

• حسابات خدمة Google: استخدم نوع بيانات الاعتماد Google Service Account والصق البريد الإلكتروني لحساب الخدمة والمفتاح الخاص.
• مفاتيح API العادية التي تديرها خارج واجهة المستخدم: أضفها إلى ملف compose، مثل - CRM_API_KEY=yourapikey، ثم شغّل docker compose up -d، واستدعها في عقدة HTTP Request بالصيغة {{ $env.CRM_API_KEY }}.

إذا أعاد $env خطأ في الوصول، فاضبط N8N_BLOCK_ENV_ACCESS_IN_NODE=false. لا تفعل ذلك إلا إذا كان مسموحًا لكل من يستطيع تعديل سير العمل بقراءة هذه المتغيرات.

التحقق من نجاح الإعداد

انقر على Listen for test event في عقدة Webhook، ثم أرسل طلبًا تجريبيًا:

curl -i -X POST https://n8n.example.com/webhook-test/order-created \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Token: yoursecret" \
  -d '{"order_id": 1234, "total": 250}'

يجب أن تظهر البيانات في المحرر. بعد ذلك، فعّل سير العمل وكرّر الطلب على /webhook/order-created. في حالة Basic Auth، استخدم -u user:yourpassword بدلًا من الترويسة. ثم تحقق من أمرين آخرين:

• الطلب الذي لا يحتوي على الرمز المميز يعيد الخطأ 403.
• ظهور عملية تنفيذ جديدة ضمن Executions.

المشكلات الشائعة

• الخطأ 404 "The requested webhook ... is not registered": سير العمل غير مفعّل، أو انتهت مهلة مستمع الاختبار، أو أن طريقة HTTP تختلف عن إعداد العقدة. فعّل سير العمل أو انقر على Listen مرة أخرى، وتأكد من تطابق GET/POST.
• خطأ OAuth "redirect_uri_mismatch" أو "invalid redirect": رابط redirect URI لدى المزوّد لا يطابق تمامًا ما يعرضه n8n. من الأسباب الشائعة الخلط بين http وhttps، أو استخدام localhost، أو نطاق فرعي مختلف. اضبط WEBHOOK_URL وN8N_EDITOR_BASE_URL، وأعد إنشاء الحاوية، ثم انسخ الرابط من جديد.
• الخطأ 413 Request Entity Too Large: ارفع قيمة client_max_body_size في Nginx وقيمة N8N_PAYLOAD_SIZE_MAX في n8n.
• الخطأ 504 Gateway Timeout في عمليات التنفيذ الطويلة: اضبط عقدة Webhook على الاستجابة Immediately مع المعالجة في الخلفية، أو ارفع قيمة proxy_read_timeout. تذكّر أن المهلة الخاصة بالجهة المُرسِلة تظل سارية.
• روابط Webhook تظهر بالصيغة localhost:5678: المتغير WEBHOOK_URL غير مضبوط داخل الحاوية. تحقق منه باستخدام docker compose exec n8n printenv WEBHOOK_URL.

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

هل يمكنني استخدام رابط Webhook الخاص بالاختبار في بيئة الإنتاج؟

لا. رابط الاختبار لا يستجيب إلا أثناء استماع المحرر، ولطلب واحد فقط. احرص دائمًا على إعطاء الخدمات الخارجية رابط الإنتاج /webhook/ وإبقاء سير العمل مفعّلًا.

هل أحتاج إلى إعادة ربط بيانات اعتماد OAuth إذا غيّرت نطاق n8n؟

نعم. حدّث WEBHOOK_URL ورابط redirect URI لدى كل مزوّد، ثم أعد ربط جميع بيانات اعتماد OAuth2. كما تحتاج الخدمات الخارجية إلى روابط Webhook الجديدة.

هل تخزين مفاتيح API في بيانات اعتماد n8n آمن؟

نعم، طالما أنك تحمي مفتاح التشفير، لأن بيانات الاعتماد تُخزَّن مشفّرة. قيّد من يملكون صلاحية الوصول إلى المحرر، لأن المحررين يستطيعون استخدام أي بيانات اعتماد مشتركة داخل سير العمل.

هل تحتاج إلى مساعدة؟ افتح تذكرة دعم عبر https://cloudesta.com/submitticket.php مع ذكر نطاق n8n الخاص بك ونص الخطأ كما هو. يمكنك أيضًا تصفّح المزيد من الأدلة في مكتبة الشروحات من Cloudesta.