نود Respond to Webhook در N8N

نود Respond to Webhook در N8N

نود Respond to Webhook برای کنترل پاسخ HTTP یک وب‌هوک استفاده می‌شود. با کمک این نود می‌توان مشخص کرد که درخواست‌کننده چه داده‌ای، با چه کد وضعیت، چه هدرهایی و در چه قالبی دریافت کند. این قابلیت برای ساخت API، اتصال سرویس‌ها، پردازش فرم‌ها و ایجاد پاسخ‌های سفارشی بسیار کاربردی است.

معرفی نود Respond to Webhook در N8N

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

• دسته‌بندی نود: Action و Core Node
• نوع عملکرد: ارسال پاسخ HTTP برای درخواست دریافت‌شده توسط Webhook
• کاربرد اصلی: تعیین بدنه پاسخ، کد وضعیت HTTP، هدرها، فایل، متن، JSON، ریدایرکت یا JWT
• نود مکمل: Webhook

برای استفاده از این نود باید در نود Webhook، گزینه پاسخ‌دهی روی Using Respond to Webhook Node تنظیم شود. در غیر این صورت، پاسخ توسط خود نود Webhook یا بر اساس آخرین نود اجراشده ارسال خواهد شد.

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

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

ساخت API بدون برنامه‌نویسی گسترده

می‌توان با ترکیب Webhook، نودهای پردازشی و Respond to Webhook یک API ساده ایجاد کرد. درخواست توسط Webhook دریافت می‌شود، داده‌ها پردازش می‌شوند و نتیجه به‌صورت JSON برمی‌گردد.

• Webhook برای دریافت درخواست
• Edit Fields یا Code برای پردازش داده
• Respond to Webhook برای ارسال پاسخ JSON

پردازش فرم‌های سایت

اطلاعات فرم تماس یا ثبت‌نام می‌تواند از طریق Webhook وارد N8N شود. پس از ذخیره اطلاعات در Google Sheets، Airtable، Notion یا پایگاه داده، یک پیام موفقیت برای سایت ارسال می‌شود.

نمونه پاسخ:

{  "success": true,  "message": "Form submitted successfully"}

اعتبارسنجی درخواست و ارسال خطای مناسب

با استفاده از نود IF می‌توان بررسی کرد که فیلدهای ضروری وجود دارند یا خیر. در صورت معتبر بودن درخواست، پاسخ 200 یا 201 و در صورت نامعتبر بودن، پاسخ 400 ارسال می‌شود.

• Webhook برای دریافت داده
• IF برای اعتبارسنجی
• Respond to Webhook با کد 200 در مسیر موفق
• Respond to Webhook با کد 400 در مسیر خطا

برگرداندن فایل

اگر ورکفلو یک PDF، تصویر، فایل CSV یا فایل ZIP تولید یا دریافت کند، Respond to Webhook می‌تواند فایل باینری را مستقیماً برای درخواست‌کننده ارسال کند.

برای این سناریو می‌توان از نودهایی مانند HTTP Request، Read/Write Files from Disk، Convert to File یا ابزارهای تولید سند استفاده کرد.

ریدایرکت کاربر

پس از تکمیل عملیات، کاربر می‌تواند به صفحه موفقیت، صفحه پرداخت یا آدرس دیگری هدایت شود. در این حالت نوع پاسخ روی Redirect قرار می‌گیرد و URL مقصد مشخص می‌شود.

ایجاد توکن JWT

در نسخه‌هایی از N8N که گزینه JWT Token در این نود ارائه می‌شود، می‌توان داده‌های مشخصی را با یک کلید رمزنگاری امضا کرد و توکن را در پاسخ HTTP برگرداند. این قابلیت برای ایجاد توکن‌های کوتاه‌مدت یا اتصال کنترل‌شده بین سرویس‌ها کاربرد دارد.

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

پیش‌نیاز تنظیم Webhook

در نود Webhook باید پارامتر پاسخ‌دهی به شکل زیر تنظیم شود:

• Respond: Using Respond to Webhook Node

پس از این تنظیم، درخواست HTTP تا زمان رسیدن اجرای ورکفلو به Respond to Webhook منتظر دریافت پاسخ می‌ماند.

پارامتر Respond With

پارامتر Respond With تعیین می‌کند چه نوع داده‌ای به درخواست‌کننده برگردانده شود. گزینه‌های موجود ممکن است با توجه به نسخه N8N کمی متفاوت باشند.

Response Body

این فیلد در حالت‌های JSON و Text نمایش داده می‌شود و بدنه اصلی پاسخ را مشخص می‌کند.

• نوع داده در حالت JSON: شیء JSON معتبر یا Expression که یک Object تولید کند
• نوع داده در حالت Text: رشته متنی
• کاربرد: ساخت پاسخ ثابت یا پویا بر اساس داده نودهای قبلی

نمونه پاسخ JSON با Expression:

{  "success": true,  "userId": "{{$json.id}}",  "message": "User created successfully"}

اگر کل فیلد در حالت Expression قرار گرفته باشد، می‌توان یک Object کامل برگرداند:

{{ {  success: true,  orderId: $json.orderId,  total: $json.total} }}

در حالت JSON باید خروجی نهایی یک ساختار معتبر باشد. وجود ویرگول اضافه، کوتیشن ناقص یا Expression نامعتبر می‌تواند اجرای نود را متوقف کند.

Response Code

این پارامتر کد وضعیت HTTP پاسخ را تعیین می‌کند.

• نوع داده: Number
• مقدار متداول پیش‌فرض: 200
• مثال موفقیت: 200
• مثال ایجاد رکورد: 201
• مثال بدون محتوا: 204
• مثال درخواست نامعتبر: 400
• مثال عدم احراز هویت: 401
• مثال عدم دسترسی: 403
• مثال پیدا نشدن اطلاعات: 404
• مثال تداخل داده: 409
• مثال خطای داخلی: 500

کد پاسخ باید با نتیجه واقعی عملیات هماهنگ باشد. برای مثال، ارسال کد 200 همراه با پیام خطا باعث می‌شود کلاینت‌ها، مانیتورها و سیستم‌های متصل نتوانند نتیجه درخواست را به‌درستی تشخیص دهند.

Response Headers

در بخش Response Headers می‌توان یک یا چند هدر HTTP به پاسخ اضافه کرد. هر هدر معمولاً شامل نام و مقدار است.

• Name: نام هدر
• Value: مقدار هدر

نمونه هدرهای کاربردی:

برخی هدرها ممکن است توسط N8N، وب‌سرور یا Reverse Proxy تنظیم یا بازنویسی شوند. همچنین نباید مقادیر دریافتی از کاربر بدون اعتبارسنجی مستقیماً در هدر پاسخ قرار گیرند.

Response Data Source

در حالت‌های First Incoming Item و All Incoming Items، داده از آیتم‌های ورودی همین نود خوانده می‌شود. بنابراین اگر لازم است ساختار پاسخ تغییر کند، بهتر است قبل از Respond to Webhook از Edit Fields، Code یا Item Lists استفاده شود.

Binary Property یا Input Field Name

در حالت Binary File باید نام فیلد باینری حاوی فایل مشخص شود.

• نوع داده: String
• مقدار رایج: data
• کاربرد: معرفی نام property موجود در بخش binary آیتم
• مثال: اگر فایل در binary.invoice قرار دارد، نام فیلد باید invoice باشد.

اگر نام فیلد اشتباه باشد یا آیتم ورودی فایل باینری نداشته باشد، نود قادر به ارسال فایل نخواهد بود.

Redirect URL

این فیلد در حالت Redirect نمایش داده می‌شود و آدرس مقصد را مشخص می‌کند.

• نوع داده: String یا URL
• مثال ثابت: https://example.com/success
• مثال پویا: {{$json.redirectUrl}}

بهتر است مقصد ریدایرکت از میان دامنه‌های مجاز انتخاب شود. استفاده مستقیم از URL دریافت‌شده از کاربر می‌تواند آسیب‌پذیری Open Redirect ایجاد کند.

JWT Key

در حالت JWT Token، کلید مورد استفاده برای امضای توکن در این بخش قرار می‌گیرد.

• نوع داده: String یا Secret
• کاربرد: امضای JWT
• نکته امنیتی: کلید نباید در داده خروجی، لاگ عمومی یا نودهای قابل مشاهده ذخیره شود.

نوع کلید باید با الگوریتم انتخاب‌شده هماهنگ باشد. الگوریتم‌های HMAC معمولاً از Secret مشترک و الگوریتم‌های RSA یا ECDSA از کلیدهای متناسب استفاده می‌کنند.

JWT Algorithm

این پارامتر الگوریتم امضای JWT را تعیین می‌کند. گزینه‌های قابل انتخاب به نسخه N8N و پیاده‌سازی نود بستگی دارند.

• نوع داده: Enum
• نمونه الگوریتم: HS256
• نکته: سرویس دریافت‌کننده باید از همان الگوریتم و کلید سازگار استفاده کند.

نکات مهم هنگام پیکربندی

• نود Webhook باید روی حالت پاسخ‌دهی با Respond to Webhook تنظیم شده باشد.
• پاسخ باید قبل از پایان مهلت انتظار کلاینت، پراکسی یا سرویس مبدأ ارسال شود.
• برای پاسخ JSON، ساختار نهایی باید معتبر باشد.
• برای کدهای 204 و برخی کدهای خاص HTTP نباید بدنه پاسخ ارسال شود.
• برای فایل‌های بزرگ باید محدودیت حافظه، زمان اجرا و تنظیمات Reverse Proxy بررسی شود.
• در حالت Production، ورکفلو باید Active باشد و درخواست به Production URL نود Webhook ارسال شود.
• Test URL فقط هنگام گوش‌دادن نود Webhook در محیط ویرایشگر قابل استفاده است.
• در هر درخواست HTTP فقط یک پاسخ نهایی قابل ارسال است.

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

ورودی نود

Respond to Webhook داده را از نود قبلی دریافت می‌کند. این داده الزاماً همان خروجی خام Webhook نیست؛ هر نودی که میان Webhook و Respond to Webhook قرار گرفته باشد می‌تواند ساختار آن را تغییر دهد.

نمونه داده خامی که ممکن است از Webhook دریافت شود:

{  "headers": {    "host": "automation.example.com",    "content-type": "application/json",    "user-agent": "Example Client"  },  "params": {},  "query": {    "source": "website"  },  "body": {    "name": "Ali",    "email": "ali@example.com"  },  "webhookUrl": "https://automation.example.com/webhook/contact",  "executionMode": "production"}

برای دسترسی به بخش‌های مختلف این داده می‌توان از Expression استفاده کرد:

• {{$json.body.name}} برای نام
• {{$json.body.email}} برای ایمیل
• {{$json.query.source}} برای پارامتر Query
• {{$json.headers["user-agent"]}} برای هدر User-Agent

نمونه ورودی پردازش‌شده

معمولاً بهتر است پیش از ارسال پاسخ، داده‌ها با Edit Fields یا Code به ساختاری تمیز تبدیل شوند:

{  "success": true,  "customer": {    "id": 8451,    "name": "Ali"  },  "createdAt": "2026-07-14T10:30:00.000Z"}

خروجی HTTP

خروجی اصلی این نود، پاسخی است که به کلاینت HTTP ارسال می‌شود. این پاسخ از سه بخش مهم تشکیل شده است:

• Status Code: مانند 200 یا 400
• Headers: مانند Content-Type و Cache-Control
• Body: داده JSON، متن، فایل یا محتوای خالی

نمونه پاسخ HTTP:

HTTP/1.1 201 CreatedContent-Type: application/json; charset=utf-8Cache-Control: no-store{  "success": true,  "customerId": 8451}

خروجی داخل ورکفلو

در نسخه‌های متداول N8N، اجرای ورکفلو می‌تواند پس از Respond to Webhook ادامه پیدا کند و آیتم‌های ورودی نود برای نودهای بعدی قابل استفاده باشند. این رفتار امکان ارسال سریع پاسخ و ادامه برخی پردازش‌ها را فراهم می‌کند.

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

مثال عملی: ساخت API ثبت کاربر

ساختار ورکفلو

• Webhook با متد POST
• IF برای بررسی ایمیل
• Postgres یا Google Sheets برای ثبت اطلاعات
• Edit Fields برای ساخت پاسخ
• Respond to Webhook برای ارسال نتیجه

مسیر موفقیت

در صورتی که ایمیل معتبر باشد و اطلاعات با موفقیت ذخیره شوند، Respond to Webhook با تنظیمات زیر اجرا می‌شود:

• Respond With: JSON
• Response Code: 201
• Response Header: Content-Type: application/json
• Response Body:

{  "success": true,  "userId": "{{$json.id}}",  "message": "User created successfully"}

مسیر خطا

اگر ایمیل ارسال نشده باشد، یک Respond to Webhook دیگر در خروجی False نود IF قرار می‌گیرد:

• Respond With: JSON
• Response Code: 400
• Response Body:

{  "success": false,  "error": {    "code": "EMAIL_REQUIRED",    "message": "Email is required"  }}

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

ارسال پاسخ سریع و ادامه پردازش

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

نمونه پاسخ:

{  "accepted": true,  "status": "processing",  "trackingId": "{{$execution.id}}"}

کد 202 نشان می‌دهد درخواست پذیرفته شده، اما پردازش آن هنوز کامل نشده است.

ایجاد ساختار ثابت برای پاسخ API

بهتر است تمام endpointها از یک قرارداد مشخص استفاده کنند. برای مثال:

{  "success": true,  "data": {},  "error": null,  "meta": {    "requestId": "{{$execution.id}}"  }}

برای خطا نیز می‌توان ساختار ثابتی داشت:

{  "success": false,  "data": null,  "error": {    "code": "VALIDATION_ERROR",    "message": "Invalid request data"  },  "meta": {    "requestId": "{{$execution.id}}"  }}

مدیریت چند مسیر پاسخ

در ورکفلوهایی که نود IF یا Switch دارند، می‌توان در هر شاخه یک Respond to Webhook قرار داد. باید اطمینان حاصل شود که برای هر اجرای درخواست فقط یکی از شاخه‌ها پاسخ ارسال می‌کند.

• مسیر موفقیت با کد 200 یا 201
• مسیر داده نامعتبر با کد 400 یا 422
• مسیر عدم دسترسی با کد 401 یا 403
• مسیر پیدا نشدن رکورد با کد 404
• مسیر خطای داخلی با کد 500

تنظیم CORS

اگر Webhook مستقیماً از مرورگر فراخوانی می‌شود، ممکن است تنظیم هدرهای CORS ضروری باشد.

• Access-Control-Allow-Origin: دامنه مجاز
• Access-Control-Allow-Methods: POST, GET, OPTIONS
• Access-Control-Allow-Headers: Content-Type, Authorization

استفاده از مقدار * برای Access-Control-Allow-Origin در APIهای حساس توصیه نمی‌شود. برای درخواست‌های Preflight با متد OPTIONS نیز ممکن است به مسیر یا Webhook جداگانه نیاز باشد.

ارسال فایل با نام مناسب

برای دانلود فایل بهتر است هدر Content-Disposition تنظیم شود:

Content-Disposition: attachment; filename=monthly-report.pdf

همچنین MIME Type فایل باید در metadata باینری یا هدر Content-Type به‌درستی مشخص شود.

استفاده از شناسه اجرا برای ردیابی

قرار دادن شناسه Execution در هدر یا بدنه پاسخ، عیب‌یابی را ساده‌تر می‌کند:

{  "success": false,  "message": "Internal processing error",  "requestId": "{{$execution.id}}"}

این شناسه بدون افشای جزئیات داخلی خطا، امکان پیدا کردن اجرای مرتبط در N8N را فراهم می‌کند.

جلوگیری از افشای اطلاعات حساس

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

مدیریت خطا با Error Workflow

Error Workflow برای ثبت و اطلاع‌رسانی خطاها مفید است، اما همیشه جایگزین پاسخ مستقیم به درخواست HTTP نیست. برای خطاهای قابل پیش‌بینی مانند اعتبارسنجی ناموفق باید در همان ورکفلو یک مسیر پاسخ مشخص طراحی شود.

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

تنظیم نبودن Webhook برای استفاده از Respond to Webhook

اگر حالت پاسخ‌دهی Webhook روی گزینه دیگری باشد، Respond to Webhook نمی‌تواند پاسخ مورد انتظار را ارسال کند.

راه‌حل: در نود Webhook، گزینه Respond را روی Using Respond to Webhook Node قرار دهید.

پایان یافتن مهلت انتظار درخواست

اگر پردازش ورکفلو طولانی باشد، مرورگر، کلاینت، Load Balancer یا Reverse Proxy ممکن است پیش از رسیدن اجرا به Respond to Webhook اتصال را قطع کند.

راه‌حل: پاسخ 202 را زودتر ارسال کنید و پردازش سنگین را پس از پاسخ یا در یک ورکفلو جداگانه انجام دهید. محدودیت Timeout زیرساخت نیز باید بررسی شود.

ارسال بیش از یک پاسخ

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

راه‌حل: شاخه‌های ورکفلو را به‌صورت انحصاری طراحی کنید و از IF، Switch یا Merge با منطق مناسب استفاده کنید.

JSON نامعتبر

خطاهای نگارشی مانند کوتیشن ناقص، ویرگول اضافه یا Expression نامعتبر باعث شکست پاسخ JSON می‌شوند.

راه‌حل: فیلد را در حالت Expression قرار دهید و یک Object تولید کنید، یا JSON را پیش از استفاده اعتبارسنجی کنید.

پیدا نشدن فیلد باینری

در حالت Binary File، اگر Binary Property اشتباه باشد، فایل ارسال نمی‌شود.

راه‌حل: خروجی نود قبلی را بررسی کنید و نام دقیق property موجود در بخش binary را وارد کنید.

استفاده اشتباه از Test URL و Production URL

Test URL معمولاً فقط هنگام اجرای دستی و فعال بودن حالت Listen for Test Event پاسخ می‌دهد. Production URL به ورکفلو فعال نیاز دارد.

راه‌حل: برای آزمایش از Test URL و برای سرویس واقعی از Production URL استفاده کنید.

کد وضعیت ناسازگار با بدنه

ارسال کد 200 برای خطا یا ارسال بدنه همراه با کد 204 می‌تواند باعث رفتار نادرست کلاینت شود.

راه‌حل: کد وضعیت، هدرها و بدنه را مطابق استاندارد HTTP تنظیم کنید.

مشکلات CORS

ممکن است Webhook در ابزارهایی مانند Postman کار کند، اما مرورگر به دلیل نبود هدرهای CORS درخواست را مسدود کند.

راه‌حل: هدرهای CORS را برای دامنه‌ها، متدها و هدرهای مجاز تنظیم کنید و درخواست OPTIONS را نیز در نظر بگیرید.

محدودیت فایل‌های بزرگ

ارسال فایل‌های بزرگ می‌تواند حافظه و زمان اجرای N8N را افزایش دهد و با محدودیت Reverse Proxy یا تنظیمات حجم Payload مواجه شود.

راه‌حل: برای فایل‌های بسیار بزرگ، فایل را در فضای ذخیره‌سازی ابری قرار دهید و لینک دانلود زمان‌دار برگردانید.

باز بودن Endpoint عمومی

Webhook عمومی بدون احراز هویت می‌تواند توسط افراد ناشناس فراخوانی شود و منابع سیستم را مصرف کند.

راه‌حل: از قابلیت Authentication نود Webhook، بررسی API Key، امضای HMAC، محدودسازی IP یا Rate Limiting در Reverse Proxy استفاده کنید.

Open Redirect

اگر Redirect URL مستقیماً از ورودی کاربر گرفته شود، مهاجم می‌تواند کاربران را به دامنه مخرب هدایت کند.

راه‌حل: دامنه مقصد را با فهرست دامنه‌های مجاز مقایسه کنید یا مسیرهای ریدایرکت را به‌صورت ثابت تعریف کنید.

عدم پشتیبانی از چند پاسخ مرحله‌ای معمولی

Respond to Webhook برای ارسال یک پاسخ HTTP نهایی طراحی شده است و نمی‌توان با چند نود Respond to Webhook چند پاسخ مستقل برای یک درخواست معمولی فرستاد. قابلیت‌های Streaming، در صورت وجود در نسخه مورد استفاده، تنظیمات و نودهای سازگار مخصوص خود را دارند.

ایده‌ها

• API تولید فاکتور: دریافت اطلاعات سفارش، ساخت PDF و برگرداندن مستقیم فایل فاکتور.
• سیستم پیگیری پردازش: پذیرش درخواست با کد 202، تولید Tracking ID و ارائه endpoint جداگانه برای مشاهده وضعیت.
• درگاه کوتاه‌کننده لینک: دریافت یک شناسه از URL، پیدا کردن مقصد در پایگاه داده و ریدایرکت کاربر.
• API اعتبارسنجی داده: دریافت ایمیل، شماره تلفن یا کد ملی، بررسی فرمت و ارسال پاسخ استاندارد JSON.
• درگاه یکپارچه سرویس‌های داخلی: دریافت درخواست، فراخوانی چند API با HTTP Request و بازگرداندن یک پاسخ ترکیبی و یکپارچه.

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

• مستندات رسمی نود Respond to Webhook در N8N
• مستندات رسمی نود Webhook در N8N
• راهنمای توسعه ورکفلو با Webhook
• دوره‌های رسمی آموزش N8N
• بحث‌های انجمن N8N درباره Respond to Webhook
• کانال رسمی N8N در YouTube
• مرجع کدهای وضعیت HTTP در MDN
• مرجع هدرهای HTTP در MDN