نود On Webhook Call در N8N

نود On Webhook Call در N8N

نود On Webhook Call که در N8N معمولاً با نام Webhook شناخته می‌شود، یکی از مهم‌ترین نودهای Trigger برای شروع خودکار ورکفلوها از طریق درخواست HTTP است. هر زمان یک سیستم خارجی، وب‌سایت، فرم، اپلیکیشن، سرویس پرداخت یا API به آدرس Webhook این نود درخواست ارسال کند، ورکفلو فعال می‌شود و داده‌های دریافتی وارد جریان اتوماسیون می‌شوند.

معرفی نود در N8N

نود On Webhook Call یک نقطه ورودی برای ورکفلوهای N8N ایجاد می‌کند. این نقطه ورودی یک URL اختصاصی است که می‌تواند درخواست‌های HTTP مانند GET، POST، PUT، PATCH و DELETE را دریافت کند.

  • دسته‌بندی نود: Trigger
  • کارکرد اصلی: شروع اجرای ورکفلو هنگام دریافت یک درخواست HTTP
  • اهمیت در ورکفلوها: اتصال N8N به سیستم‌های خارجی، دریافت داده از فرم‌ها، APIها، وب‌سایت‌ها، سرویس‌های پرداخت، CRM، GitHub، Telegram، Slack و سایر سرویس‌ها

این نود برای زمانی مناسب است که می‌خواهید یک فرایند دقیقاً بعد از رخ دادن یک اتفاق بیرونی شروع شود؛ مثلاً ثبت سفارش، ارسال فرم تماس، پرداخت موفق، ایجاد تیکت، ثبت لید یا دریافت اعلان از یک سرویس دیگر.

موارد استفاده

دریافت اطلاعات فرم سایت

یکی از رایج‌ترین کاربردهای نود On Webhook Call دریافت داده‌های فرم از سایت است. برای مثال، وقتی کاربر فرم تماس را در وب‌سایت پر می‌کند، داده‌ها با متد POST به Webhook ارسال می‌شوند و سپس N8N می‌تواند آن‌ها را در Google Sheets ذخیره کند، برای تیم فروش ایمیل بفرستد یا در CRM ثبت کند.

  • On Webhook Call برای دریافت اطلاعات فرم
  • Edit Fields یا Set برای مرتب‌سازی داده‌ها
  • Google Sheets برای ذخیره اطلاعات
  • Gmail یا Slack برای ارسال اعلان

پردازش پرداخت‌های آنلاین

درگاه‌های پرداخت معمولاً بعد از پرداخت موفق یا ناموفق، یک Webhook به سیستم شما ارسال می‌کنند. با این نود می‌توانید نتیجه پرداخت را دریافت کرده و بر اساس آن سفارش را تأیید، فاکتور صادر یا پیام اطلاع‌رسانی ارسال کنید.

  • دریافت وضعیت پرداخت از سرویس پرداخت
  • بررسی شناسه سفارش و مبلغ پرداختی
  • به‌روزرسانی دیتابیس یا CRM
  • ارسال پیامک یا ایمیل تأیید پرداخت

اتصال GitHub یا GitLab به فرایندهای داخلی

می‌توانید برای رویدادهایی مثل push، pull request یا issue جدید، یک Webhook تعریف کنید. سپس N8N پس از دریافت رویداد، پیام Slack ارسال می‌کند، تیکت ایجاد می‌کند یا عملیات CI/CD سفارشی را شروع می‌کند.

ساخت API ساده بدون کدنویسی سنگین

نود On Webhook Call می‌تواند مانند یک API Endpoint عمل کند. شما می‌توانید درخواست دریافت کنید، داده را پردازش کنید و با استفاده از نود Respond to Webhook پاسخ JSON سفارشی برگردانید.

ترکیب با نودهای دیگر

  • IF: بررسی شرط‌ها؛ مثلاً اگر وضعیت پرداخت موفق بود ادامه بده
  • Switch: مسیرهای مختلف بر اساس نوع رویداد
  • Code: پردازش پیشرفته داده‌ها با JavaScript
  • HTTP Request: ارسال داده دریافتی به یک API دیگر
  • Respond to Webhook: ارسال پاسخ سفارشی به درخواست‌دهنده
  • Postgres، MySQL یا MongoDB: ذخیره داده‌ها در دیتابیس
  • Slack، Telegram، Gmail: ارسال اعلان و پیام

پارامترها و تنظیمات

تنظیمات نود On Webhook Call مشخص می‌کند که Webhook با چه آدرسی، چه متدی، چه سطح امنیتی و چه نوع پاسخی کار کند. بعضی گزینه‌ها ممکن است بسته به نسخه N8N کمی متفاوت باشند، اما ساختار کلی نود مشابه است.

HTTP Method

  • نوع داده: انتخابی / Enum
  • مقادیر رایج: GET، POST، PUT، PATCH، DELETE، HEAD
  • توضیح کاربرد: مشخص می‌کند Webhook به چه نوع درخواست HTTP پاسخ دهد.
  • مثال عملی: برای دریافت داده فرم معمولاً از POST استفاده می‌شود. برای خواندن یک مقدار ساده از URL می‌توان از GET استفاده کرد.
  • نکته مهم: اگر Webhook را با متد POST ساخته باشید اما درخواست با GET ارسال شود، معمولاً پاسخ خطای Not Found یا Method Not Allowed دریافت می‌شود.

Path

  • نوع داده: String
  • توضیح کاربرد: مسیر اختصاصی Webhook را مشخص می‌کند. این مسیر بخشی از URL نهایی Webhook خواهد بود.
  • مثال عملی: اگر مقدار Path برابر باشد با contact-form، آدرس Webhook چیزی شبیه به این خواهد بود: https://your-n8n-domain.com/webhook/contact-form
  • نکته مهم: بهتر است مسیرها کوتاه، خوانا و یکتا باشند. برای امنیت بیشتر از مسیرهای خیلی قابل حدس مانند test یا form به‌تنهایی استفاده نشود.

Dynamic Path یا پارامترهای مسیر

  • نوع داده: String
  • توضیح کاربرد: در بعضی سناریوها می‌توان بخشی از مسیر را به‌صورت متغیر تعریف کرد تا مقدار آن در خروجی نود داخل بخش params قرار بگیرد.
  • مثال عملی: مسیر orders/:orderId می‌تواند مقدار orderId را از URL دریافت کند.
  • نمونه URL: https://your-n8n-domain.com/webhook/orders/12345
  • خروجی مورد انتظار: مقدار 12345 در params.orderId قرار می‌گیرد.

Authentication

  • نوع داده: انتخابی / Enum
  • مقادیر رایج: None، Basic Auth، Header Auth، JWT Auth
  • توضیح کاربرد: سطح امنیت Webhook را مشخص می‌کند و تعیین می‌کند چه درخواست‌هایی مجاز به اجرای ورکفلو باشند.
  • مثال عملی: برای یک Webhook داخلی می‌توانید از Header Auth استفاده کنید و یک کلید مخفی مانند x-api-key ارسال کنید.
  • نکته مهم: در محیط Production بهتر است Webhook بدون احراز هویت فقط در شرایط خاص و کنترل‌شده استفاده شود.

Credentials برای Authentication

  • نوع داده: Credential
  • توضیح کاربرد: اگر Authentication فعال باشد، باید Credential مرتبط با روش انتخاب‌شده را تعریف کنید.
  • مثال عملی: در Basic Auth یک نام کاربری و رمز عبور تعریف می‌شود. در Header Auth نام هدر و مقدار مخفی مشخص می‌شود.
  • نکته مهم: مقادیر حساس مانند API Key یا Token را مستقیم داخل نام مسیر یا پارامترهای Query قرار ندهید.

Respond

  • نوع داده: انتخابی / Enum
  • مقادیر رایج: Immediately، When Last Node Finishes، Using Respond to Webhook Node
  • توضیح کاربرد: مشخص می‌کند N8N چه زمانی و چگونه به درخواست HTTP پاسخ دهد.
  • مثال عملی: اگر می‌خواهید فوراً پاسخ 200 برگردد و پردازش در پس‌زمینه ادامه پیدا کند، گزینه Immediately مناسب است. اگر می‌خواهید نتیجه نهایی ورکفلو به کاربر برگردد، گزینه Using Respond to Webhook Node مناسب‌تر است.

Respond: Immediately

  • نوع داده: حالت پاسخ‌دهی
  • توضیح کاربرد: بلافاصله بعد از دریافت درخواست، پاسخ به سرویس ارسال‌کننده برگردانده می‌شود.
  • مثال عملی: برای Webhook سرویس‌هایی که Timeout کوتاه دارند، مثل برخی درگاه‌های پرداخت یا سرویس‌های پیام‌رسان، این حالت می‌تواند مناسب باشد.
  • نکته مهم: در این حالت معمولاً نتیجه پردازش نهایی ورکفلو به درخواست‌دهنده برگردانده نمی‌شود.

Respond: When Last Node Finishes

  • نوع داده: حالت پاسخ‌دهی
  • توضیح کاربرد: N8N صبر می‌کند تا آخرین نود اجرا شود و سپس خروجی را به درخواست‌دهنده برمی‌گرداند.
  • مثال عملی: دریافت یک شناسه کاربر، جستجو در دیتابیس و برگرداندن اطلاعات کاربر به‌صورت JSON.
  • نکته مهم: اگر اجرای ورکفلو طولانی شود، ممکن است درخواست HTTP سمت کلاینت Timeout شود.

Respond: Using Respond to Webhook Node

  • نوع داده: حالت پاسخ‌دهی
  • توضیح کاربرد: پاسخ نهایی توسط نود جداگانه Respond to Webhook ساخته و ارسال می‌شود.
  • مثال عملی: ساخت پاسخ سفارشی شامل status، message و data برای یک API داخلی.
  • نکته مهم: در این حالت باید حتماً در مسیر اجرای ورکفلو یک نود Respond to Webhook قرار بگیرد، در غیر این صورت درخواست ممکن است بدون پاسخ مناسب باقی بماند یا Timeout شود.

Response Code

  • نوع داده: Number
  • توضیح کاربرد: کد وضعیت HTTP پاسخ را تعیین می‌کند.
  • مثال عملی: کد 200 برای موفقیت، 201 برای ایجاد موفق رکورد، 400 برای درخواست نامعتبر، 401 برای عدم احراز هویت و 500 برای خطای داخلی.
  • نکته مهم: انتخاب کد پاسخ صحیح برای ارتباط درست با سرویس‌های خارجی بسیار مهم است.

Response Data

  • نوع داده: انتخابی / Enum
  • توضیح کاربرد: مشخص می‌کند چه داده‌ای در پاسخ Webhook برگردانده شود.
  • مقادیر رایج: First Entry JSON، All Entries، No Response Body، Binary Data
  • مثال عملی: اگر خروجی نهایی فقط یک آبجکت JSON دارد، First Entry JSON انتخاب مناسبی است. اگر چند آیتم تولید شده، All Entries می‌تواند کل نتایج را برگرداند.

Response Headers

  • نوع داده: Key / Value
  • توضیح کاربرد: هدرهای سفارشی را به پاسخ HTTP اضافه می‌کند.
  • مثال عملی: اضافه کردن Content-Type: application/json یا Cache-Control: no-store
  • نکته مهم: برای APIها بهتر است Content-Type پاسخ به‌درستی تنظیم شود.

Allowed Origins یا CORS

  • نوع داده: String
  • توضیح کاربرد: مشخص می‌کند چه دامنه‌هایی اجازه ارسال درخواست از مرورگر به این Webhook را داشته باشند.
  • مثال عملی: اگر فرم سایت شما روی https://example.com قرار دارد، می‌توانید همین دامنه را به‌عنوان Origin مجاز تنظیم کنید.
  • نکته مهم: مقدار * همه Originها را مجاز می‌کند، اما برای محیط Production همیشه انتخاب امنی نیست.

Raw Body

  • نوع داده: Boolean
  • توضیح کاربرد: بدنه درخواست را به‌شکل خام دریافت می‌کند.
  • مثال عملی: برای اعتبارسنجی امضای Webhook در سرویس‌هایی مانند Stripe، GitHub یا Shopify معمولاً نیاز است متن خام Body دقیقاً همان‌طور که ارسال شده بررسی شود.
  • نکته مهم: اگر Raw Body فعال باشد، نحوه دسترسی به داده‌ها ممکن است با حالت JSON معمولی متفاوت باشد.

Binary Data

  • نوع داده: Boolean یا تنظیم مرتبط با فایل
  • توضیح کاربرد: برای دریافت فایل‌ها از طریق multipart/form-data استفاده می‌شود.
  • مثال عملی: دریافت تصویر پروفایل، فایل رزومه، فاکتور PDF یا فایل CSV از یک فرم آپلود.
  • نکته مهم: فایل‌های دریافتی معمولاً در بخش binary خروجی نود قرار می‌گیرند، نه فقط در json.

Binary Property

  • نوع داده: String
  • توضیح کاربرد: نام پراپرتی‌ای را مشخص می‌کند که فایل دریافت‌شده در آن ذخیره می‌شود.
  • مثال عملی: اگر نام فیلد آپلود در فرم resume باشد، فایل ممکن است در binary.resume قرار بگیرد.
  • نکته مهم: نام فیلد فایل در فرم HTML باید با ساختاری که در N8N انتظار دارید هماهنگ باشد.

Ignore Bots

  • نوع داده: Boolean
  • توضیح کاربرد: برخی درخواست‌های شناخته‌شده از سمت ربات‌ها یا crawlerها را نادیده می‌گیرد.
  • مثال عملی: جلوگیری از اجرای ناخواسته ورکفلو هنگام بررسی لینک توسط بعضی سرویس‌ها یا شبکه‌های اجتماعی.
  • نکته مهم: این گزینه جایگزین احراز هویت و کنترل امنیتی واقعی نیست.

Test URL و Production URL

  • نوع داده: URL
  • توضیح کاربرد: نود Webhook معمولاً دو آدرس دارد؛ یکی برای تست هنگام کار در ادیتور و یکی برای استفاده واقعی در محیط Production.
  • Test URL: فقط زمانی فعال است که workflow را در حالت تست اجرا کرده باشید و N8N منتظر دریافت درخواست باشد.
  • Production URL: زمانی کار می‌کند که workflow فعال باشد.
  • نکته مهم: استفاده اشتباه از Test URL در سرویس‌های واقعی یکی از خطاهای رایج است.

ورودی‌ها و خروجی‌ها

ورودی نود

از آنجا که On Webhook Call یک Trigger Node است، ورودی آن از نود قبلی نمی‌آید. این نود با دریافت یک درخواست HTTP از بیرون N8N فعال می‌شود. داده‌های ورودی می‌توانند از بخش‌های مختلف درخواست HTTP باشند.

  • Headers: اطلاعات هدرهای HTTP مانند content-type، user-agent، authorization
  • Query Parameters: مقادیر ارسال‌شده در URL بعد از علامت ?
  • Route Params: پارامترهای متغیر در مسیر Webhook
  • Body: بدنه درخواست، معمولاً JSON، Form Data یا Raw Body
  • Binary: فایل‌های آپلودشده مانند تصویر، PDF، CSV یا ZIP

خروجی نود

خروجی نود معمولاً یک آیتم شامل اطلاعات کامل درخواست دریافتی است. این داده‌ها در ادامه ورکفلو توسط نودهای دیگر قابل استفاده هستند.

{  "headers": {    "host": "your-n8n-domain.com",    "content-type": "application/json",    "user-agent": "Example Client"  },  "params": {    "orderId": "12345"  },  "query": {    "source": "website",    "campaign": "spring"  },  "body": {    "name": "Ali",    "email": "ali@example.com",    "message": "درخواست مشاوره"  },  "webhookUrl": "https://your-n8n-domain.com/webhook/contact-form",  "executionMode": "production"}

نمونه درخواست POST

{  "fullName": "سارا احمدی",  "phone": "09120000000",  "email": "sara@example.com",  "product": "دوره آموزشی N8N"}

نمونه خروجی برای فایل آپلودی

{  "json": {    "body": {      "name": "مهدی رضایی"    }  },  "binary": {    "resume": {      "fileName": "resume.pdf",      "mimeType": "application/pdf",      "fileExtension": "pdf"    }  }}

نکات پیشرفته و ترفندها

استفاده از Respond to Webhook برای ساخت API حرفه‌ای

اگر می‌خواهید Webhook فقط یک دریافت‌کننده ساده نباشد و مثل یک API واقعی پاسخ بدهد، بهتر است از حالت Using Respond to Webhook Node استفاده کنید. با این روش می‌توانید پاسخ‌های کاملاً سفارشی بسازید.

{  "success": true,  "message": "اطلاعات با موفقیت ثبت شد",  "data": {    "requestId": "REQ-1001"  }}

اعتبارسنجی امضا برای Webhookهای حساس

بعضی سرویس‌ها همراه درخواست Webhook یک امضای امنیتی در Header ارسال می‌کنند. برای اعتبارسنجی این امضا باید معمولاً Raw Body را فعال کنید و سپس با نود Code مقدار امضا را بررسی کنید.

  • فعال‌سازی Raw Body
  • دریافت مقدار امضا از headers
  • محاسبه HMAC با کلید مخفی
  • مقایسه امضای محاسبه‌شده با امضای دریافتی

جلوگیری از اجرای تکراری

بعضی سرویس‌ها اگر پاسخ مناسب دریافت نکنند، Webhook را چند بار ارسال می‌کنند. برای جلوگیری از ثبت تکراری داده، بهتر است از شناسه یکتا مانند paymentId، eventId یا orderId استفاده کنید و قبل از پردازش، وجود آن را در دیتابیس بررسی کنید.

پاسخ سریع برای جلوگیری از Timeout

اگر پردازش شما طولانی است، بهتر است ابتدا پاسخ سریع به سرویس ارسال‌کننده بدهید و سپس ادامه عملیات را در مسیرهای بعدی انجام دهید. در چنین حالتی می‌توان از Respond Immediately یا ترکیب Webhook با Execute Workflow استفاده کرد.

استفاده از IF و Switch برای مدیریت چند نوع رویداد

اگر یک سرویس چند نوع رویداد به یک Webhook ارسال می‌کند، می‌توانید با Switch مقدار eventType را بررسی کرده و برای هر رویداد مسیر جداگانه بسازید.

  • eventType برابر payment.success: تأیید سفارش
  • eventType برابر payment.failed: ارسال پیام خطا
  • eventType برابر user.created: ثبت کاربر در CRM
  • eventType برابر ticket.created: ایجاد پیام در Slack

استفاده از Environment Variable برای URL درست در Production

در نصب‌های Self-hosted اگر دامنه، پروکسی یا SSL به‌درستی تنظیم نشده باشد، ممکن است Production URL اشتباه ساخته شود. در این حالت باید تنظیمات مربوط به دامنه عمومی N8N مانند WEBHOOK_URL به‌درستی پیکربندی شود.

ثبت لاگ برای دیباگ بهتر

برای Webhookهای مهم، بهتر است داده خام دریافتی، زمان دریافت، IP یا شناسه رویداد را در دیتابیس یا فایل لاگ ذخیره کنید. این کار در بررسی خطاها و مغایرت‌ها بسیار مفید است.

محدودیت‌ها و خطاها

محدودیت‌ها

  • نود On Webhook Call فقط زمانی اجرا می‌شود که درخواست HTTP به URL صحیح ارسال شود.
  • Test URL فقط در حالت اجرای دستی و زمانی که نود منتظر درخواست است کار می‌کند.
  • Production URL فقط وقتی کار می‌کند که workflow فعال باشد.
  • درخواست‌های بسیار بزرگ یا فایل‌های حجیم ممکن است با محدودیت سرور، پراکسی یا تنظیمات N8N مواجه شوند.
  • اگر پردازش ورکفلو طولانی باشد، سرویس ارسال‌کننده ممکن است قبل از دریافت پاسخ Timeout شود.
  • این نود به‌تنهایی جایگزین لایه امنیتی کامل API Gateway نیست.
  • برای دریافت Webhook از اینترنت، نمونه N8N باید از بیرون قابل دسترس باشد.

خطای 404 Not Found

  • دلیل رایج: آدرس Webhook اشتباه است، workflow فعال نیست یا از Test URL خارج از حالت تست استفاده شده است.
  • راه‌حل: URL را بررسی کنید، workflow را فعال کنید و مطمئن شوید از Production URL برای محیط واقعی استفاده می‌شود.

خطای Method Not Allowed یا اجرا نشدن Webhook

  • دلیل رایج: متد درخواست با متد تنظیم‌شده در نود یکی نیست.
  • راه‌حل: اگر نود روی POST تنظیم شده، درخواست هم باید با POST ارسال شود.

خطای 401 Unauthorized یا 403 Forbidden

  • دلیل رایج: اطلاعات احراز هویت اشتباه است یا Header مورد انتظار ارسال نشده است.
  • راه‌حل: Credential، نام Header، مقدار Token، نام کاربری و رمز عبور را بررسی کنید.

خطای Timeout

  • دلیل رایج: اجرای ورکفلو بیش از حد طول کشیده یا نود Respond to Webhook اجرا نشده است.
  • راه‌حل: از Respond Immediately استفاده کنید یا مسیر پاسخ‌دهی را کوتاه‌تر کنید. در حالت Using Respond to Webhook Node مطمئن شوید همه مسیرهای ممکن به یک پاسخ ختم می‌شوند.

خطای CORS در مرورگر

  • دلیل رایج: درخواست از دامنه‌ای ارسال شده که در Allowed Origins مجاز نیست.
  • راه‌حل: دامنه سایت را در تنظیمات CORS وارد کنید و Headerهای لازم را بررسی کنید.

Body خالی یا ناقص

  • دلیل رایج: Content-Type اشتباه است، داده با فرمت نامعتبر ارسال شده یا Body Parser نتوانسته محتوا را پردازش کند.
  • راه‌حل: برای JSON از Content-Type: application/json استفاده کنید و ساختار JSON را معتبر نگه دارید.

دریافت نشدن فایل

  • دلیل رایج: فرم با multipart/form-data ارسال نشده یا نام فیلد فایل با مقدار مورد انتظار هماهنگ نیست.
  • راه‌حل: تنظیمات فرم، نام فیلد فایل و بخش binary خروجی نود را بررسی کنید.

ایده ها

  • سیستم ثبت لید هوشمند: دریافت اطلاعات فرم سایت، امتیازدهی به لید با AI، ثبت در CRM و ارسال اعلان به تیم فروش.
  • وبهوک پرداخت و صدور خودکار فاکتور: دریافت وضعیت پرداخت، بررسی سفارش، تولید فاکتور PDF و ارسال ایمیل تأیید به مشتری.
  • API داخلی برای تیم پشتیبانی: دریافت درخواست از ابزارهای داخلی، ایجاد تیکت، تخصیص کارشناس و ارسال پیام در Slack یا Telegram.
  • اتوماسیون GitHub: دریافت رویدادهای pull request، بررسی عنوان و برچسب‌ها، ارسال گزارش به کانال تیم فنی.
  • دریافت فایل و پردازش خودکار: دریافت فایل CSV از فرم، خواندن داده‌ها، ذخیره در دیتابیس و تولید گزارش روزانه.

منابع و مستندات اصلی

دسته بندی: N8N برچسب ها:

دیدگاهتان را بنویسید

نشانی ایمیل شما منتشر نخواهد شد. بخش‌های موردنیاز علامت‌گذاری شده‌اند *

11 − 3 =