نود Webhook در N8N
نود Webhook در N8N
نود Webhook یکی از مهمترین نودهای n8n است که به شما اجازه میدهد ورکفلو را با دریافت یک درخواست HTTP از بیرون (مثل سایت، اپلیکیشن، سرویسهای دیگر یا حتی Postman) اجرا کنید. به زبان ساده: هر زمان یک URL خاص در n8n فراخوانی شود، ورکفلو شما شروع میشود و دادههای ارسالشده را تحویل میگیرد.
معرفی نود در N8N
Webhook در n8n برای دریافت رویدادها (Event) و دادهها از سیستمهای دیگر استفاده میشود. به جای اینکه n8n همیشه در حال چککردن باشد، سرویس خارجی با یک درخواست HTTP، n8n را «خبر» میکند.
- کارکرد اصلی: دریافت درخواست HTTP (GET/POST/PUT/DELETE و …) و شروع اجرای ورکفلو
- دستهبندی نود: Trigger
- اهمیت در ورکفلوها: پایه بسیاری از سناریوهای اتوماسیون رویدادمحور است؛ مثل دریافت فرمها، نوتیفیکیشن پرداخت، وبهوکهای Stripe/GitHub/Shopify، یا دریافت داده از سایت و اپلیکیشن.
موارد استفاده
سناریوهای واقعی و متداول
- دریافت اطلاعات فرم سایت: کاربر فرم را ارسال میکند، وبهوک n8n داده را میگیرد، سپس در Google Sheets ذخیره میکند و یک ایمیل/پیام تأیید ارسال میکند.
- پرداخت و سفارش: سرویس پرداخت (مثل Stripe) پس از پرداخت موفق به وبهوک اطلاع میدهد؛ n8n سفارش را در CRM ثبت میکند و فاکتور میسازد.
- اتصال اپلیکیشن داخلی: اپلیکیشن شما رویدادهایی مثل “کاربر ثبتنام کرد” را به وبهوک میفرستد؛ n8n خوشآمدگویی، ساخت حساب در سرویسهای دیگر و تگگذاری را انجام میدهد.
- خودکارسازی تیکتها: یک سیستم پشتیبانی هنگام ایجاد تیکت جدید وبهوک میزند؛ n8n دستهبندی انجام میدهد و آن را به Slack/Teams ارسال میکند.
- یک API ساده بدون کدنویسی: با Webhook + چند نود Function/Set میتوانید یک API سبک بسازید که JSON تحویل بگیرد و پاسخ JSON برگرداند.
ترکیب با نودهای دیگر برای ساخت ورکفلوهای عملی
- Webhook + IF: بر اساس داده ورودی مسیرهای مختلف اجرا شود (مثلاً نوع رویداد).
- Webhook + Switch: هندلکردن چند eventType با چند مسیر.
- Webhook + Set: پاکسازی و استانداردسازی فیلدها قبل از ذخیره/ارسال.
- Webhook + HTTP Request: بعد از دریافت رویداد، داده را به APIهای دیگر ارسال کنید.
- Webhook + Respond to Webhook: پاسخ سفارشی (JSON/متن/HTML) به درخواستدهنده برگردانید.
پارامترها و تنظیمات
در n8n بسته به نسخه، نام برخی گزینهها ممکن است کمی متفاوت باشد، اما مفاهیم ثابت هستند. در ادامه تنظیمات مهم Webhook با توضیح کاربردی آمده است.
Webhook URLs (آدرسهای وبهوک)
- Test URL: برای تست در حالت طراحی. معمولاً فقط وقتی قابل استفاده است که ورکفلو در حالت تست فعال باشد.
- Production URL: برای استفاده واقعی. با فعالکردن (Activate) ورکفلو این URL همیشه آماده دریافت درخواست است.
نکته عملی: همیشه ابتدا با Test URL تست کنید، سپس ورکفلو را فعال و Production URL را در سرویس مقصد ثبت کنید.
Path (مسیر وبهوک)
- نام پارامتر: Path
- نوع داده: String
- کاربرد: بخش انتهایی URL که وبهوک با آن شناخته میشود.
- مثال عملی: اگر Path را orders/paid بگذارید، URL وبهوک چیزی شبیه /webhook/orders/paid خواهد شد.
نکته مهم: مسیر را یکتا و قابل فهم انتخاب کنید و از گذاشتن اطلاعات حساس در مسیر (مثل توکنها) پرهیز کنید.
HTTP Method (متد HTTP)
- نام پارامتر: HTTP Method
- نوع داده: Enum (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)
- کاربرد: مشخص میکند این وبهوک با چه متدی درخواست را میپذیرد.
- مثال عملی: برای ارسال JSON از سرویسها تقریباً همیشه POST استفاده میشود.
نکته مهم: اگر سرویس مقصد فقط POST میزند، متد را GET نگذارید؛ خطای 404/405 یا عدم match رخ میدهد.
Authentication (احراز هویت)
- نام پارامتر: Authentication
- نوع داده: Enum (None, Basic Auth, Header Auth و بسته به نسخه موارد دیگر)
- کاربرد: محدودکردن دسترسی به وبهوک تا هر کسی نتواند آن را صدا بزند.
- مثال عملی: در Header Auth یک هدر مثل X-Webhook-Token با مقدار مشخص دریافت کنید و فقط همان را قبول کنید.
نکته مهم: اگر وبهوک عمومی است (در اینترنت)، حتماً از یکی از روشهای احراز هویت یا یک توکن در Header استفاده کنید.
Response Mode (نحوه پاسخدهی)
- نام پارامتر: Response Mode
- نوع داده: Enum (On Received, Last Node, Using Respond to Webhook)
- کاربرد: تعیین میکند n8n چه زمانی پاسخ HTTP را برگرداند.
- مثال عملی: اگر سرویس فرستنده فقط یک تأیید سریع میخواهد، On Received باعث میشود فوری 200 OK برگردد و بقیه پردازش در ادامه انجام شود.
- On Received: سریع پاسخ میدهد؛ مناسب برای جلوگیری از timeout سرویسهای وبهوک.
- Last Node: پاسخ بر اساس خروجی آخرین نود ساخته میشود.
- Using Respond to Webhook: پاسخدهی کاملاً تحت کنترل شما با نود Respond to Webhook.
Response Code / Response Data (کد و محتوای پاسخ)
- نام پارامتر: Response Code
- نوع داده: Number
- کاربرد: تعیین کد وضعیت HTTP مثل 200، 201، 400.
- مثال عملی: برای ایجاد موفق یک منبع میتوانید 201 برگردانید.
- نام پارامتر: Response Data
- نوع داده: String/JSON (بسته به حالت پاسخ)
- کاربرد: متن یا JSON پاسخ.
- مثال عملی: {“ok”: true, “message”: “received”}
نکته مهم: اگر سرویس فرستنده انتظار پاسخ JSON دارد، هدر Content-Type و ساختار JSON را درست تنظیم کنید (معمولاً با Respond to Webhook کنترل دقیقتری دارید).
Options (گزینههای تکمیلی رایج)
- Ignore Bots / Ignore Request Body / Binary Data: بسته به نسخه ممکن است گزینههایی برای مدیریت body یا فایلها وجود داشته باشد.
- Allowed Origins (CORS): اگر از مرورگر (Front-end) مستقیم به وبهوک درخواست میزنید، تنظیم CORS مهم میشود.
- Response Headers: برای افزودن هدرهایی مثل Content-Type یا CORS headers.
نکته مهم: اگر قصد دارید از یک وباپ (در مرورگر) به وبهوک بزنید، باید CORS را درست تنظیم کنید و معمولاً روش امنتر این است که درخواست از بکاند انجام شود، نه مستقیم از مرورگر.
ورودیها و خروجیها
ورودی (Input) نود Webhook
Webhook یک Trigger است و از نود قبل ورودی نمیگیرد. ورودی آن درخواست HTTP است که شامل موارد زیر میشود:
- Body: داده ارسالی (مثلاً JSON)
- Query Parameters: پارامترهای URL مثل ?source=site
- Headers: هدرها مثل Authorization یا X-Webhook-Token
- Path Parameters: در برخی الگوها میتوان از بخشهای مسیر برای پارامتر استفاده کرد (بسته به تنظیمات و نسخه)
خروجی (Output) نود Webhook
خروجی Webhook معمولاً یک یا چند آیتم n8n است که محتوای درخواست را در فیلد json قرار میدهد. ساختار دقیق بسته به تنظیمات و نوع درخواست میتواند متفاوت باشد، اما قالب کلی شبیه نمونه زیر است:
نمونه JSON خروجی
فرض کنید یک درخواست POST با JSON زیر ارسال شده است:
{“event”:”order.paid”,”orderId”:123,”amount”:99000,”customer”:{“email”:”a@example.com”}}
خروجی در n8n معمولاً شبیه این خواهد بود:
{ “headers”: { “content-type”: “application/json”, “x-webhook-token”: “SECRET” }, “query”: { “source”: “site” }, “params”: {}, “body”: { “event”: “order.paid”, “orderId”: 123, “amount”: 99000, “customer”: { “email”: “a@example.com” } }}
نکته عملی: در بسیاری از ورکفلوها شما بیشتر با body کار دارید. برای دسترسی در Expressionها معمولاً چیزی شبیه {{$json.body.orderId}} استفاده میشود.
نکات پیشرفته و ترفندها
1) جلوگیری از Timeout با پاسخ سریع
بعضی سرویسها (مثل وبهوکهای پرداخت) اگر در چند ثانیه پاسخ 200 نگیرند، دوباره تلاش میکنند یا وبهوک را failed میزنند. برای این موارد:
- Response Mode را روی On Received بگذارید تا سریع OK برگردد.
- یا از Respond to Webhook استفاده کنید و سریع پاسخ دهید، سپس کارهای سنگین را ادامه دهید.
2) اعتبارسنجی امضا (Signature Verification)
بسیاری از سرویسها برای امنیت یک امضا (Signature) در Header میفرستند (مثل Stripe). الگوی رایج:
- امضای دریافتی را از Header بخوانید.
- با کلید محرمانه، امضای سمت خود را محاسبه کنید.
- اگر برابر نبود، پاسخ 401/403 بدهید و پردازش را قطع کنید.
برای محاسبه امضا معمولاً از نود Code (یا Function) استفاده میشود. در پروژههای واقعی، این کار جلوی تزریق درخواستهای جعلی را میگیرد.
3) ساخت API پاسخدهنده JSON با کنترل کامل
اگر میخواهید وبهوک مثل یک endpoint واقعی عمل کند:
- Response Mode را روی Using Respond to Webhook قرار دهید.
- پس از اعتبارسنجی و پردازش، با نود Respond to Webhook یک پاسخ استاندارد برگردانید.
مثال پاسخ استاندارد:
{ “ok”: true, “data”: { “orderId”: 123, “status”: “processed” }}
4) مدیریت فایلها و دادههای Binary
اگر فرم یا سرویس خارجی فایل ارسال میکند (multipart/form-data)، باید تنظیمات مربوط به Binary را بررسی کنید و در ادامه از نودهایی مثل Move Binary Data یا مقصدهایی مثل S3/Google Drive استفاده کنید. در این سناریوها، مهم است اندازه فایل و محدودیتهای سرور n8n را در نظر بگیرید.
5) ایمنسازی و محدودسازی دسترسی
- Header Auth/Basic Auth: ساده و کاربردی برای سرویسهای داخلی.
- IP Allowlist در لایه شبکه: اگر ممکن است، دسترسی را در Reverse Proxy یا Firewall محدود کنید.
- Rate Limit: در لایه پراکسی (مثل Nginx/Traefik/Cloudflare) محدودیت تعداد درخواست اعمال کنید.
محدودیتها و خطاها
محدودیتها
- وابستگی به در دسترس بودن URL عمومی: برای سرویسهای بیرونی، وبهوک باید از اینترنت قابل دسترسی باشد یا تونل (Tunnel) داشته باشید.
- محدودیت اندازه درخواست: اندازه body (خصوصاً فایلها) ممکن است توسط n8n یا Reverse Proxy محدود شود.
- پایداری Test URL: Test URL برای تست است و برای محیط واقعی مناسب نیست.
- CORS برای درخواستهای مرورگر: اگر درخواست از Front-end ارسال شود، نیازمند تنظیمات CORS است و همیشه بهترین گزینه نیست.
خطاهای رایج و راهحلها
- 404 Not Found: معمولاً Path اشتباه است یا درخواست به URL اشتباه ارسال شده است. URL Production/Test را دقیق کپی کنید و به متد توجه کنید.
- 405 Method Not Allowed: متد درخواست (مثلاً GET) با HTTP Method تنظیمشده (مثلاً POST) یکی نیست.
- 401/403 Unauthorized: احراز هویت درست تنظیم نشده یا هدر/یوزرپسورد ارسال نمیشود.
- Timeout در سرویس فرستنده: پردازش طولانی است. Response Mode را On Received کنید یا سریع با Respond to Webhook پاسخ دهید.
- Body خالی یا parse نشدن JSON: هدر Content-Type اشتباه است یا سرویس body را با فرمت غیر JSON میفرستد. در صورت نیاز raw body را ذخیره و تبدیل را در نود Code انجام دهید.
ایده ها
- سیستم ثبت لید (Lead) برای تیم فروش: وبهوک از فرم سایت دریافت کند، در CRM ثبت کند، و در Slack پیام بدهد.
- اتوماسیون گزارش خطاهای اپلیکیشن: اپلیکیشن خطا را به وبهوک بفرستد، n8n آن را دستهبندی کند و در Jira تیکت بسازد.
- API کوتاهکننده لینک داخلی: درخواست لینک را بگیرد، یک کد تولید کند، در دیتابیس ذخیره کند و پاسخ JSON برگرداند.
- پردازش سفارشهای چندکاناله: وبهوک سفارش از چند فروشگاه دریافت شود، موجودی چک شود، سپس فاکتور و پیام مشتری ارسال شود.
- تأیید خودکار مدارک: وبهوک فایل/اطلاعات را دریافت کند، به سرویس OCR بفرستد، نتیجه را ذخیره کند و وضعیت را به سیستم اصلی برگرداند.