شروع کار با workflow و webhook
هر workflow از یک Trigger شروع می‌شود و داده را بین nodeها جابه‌جا می‌کند. برای آشنایی، ابتدا یک اجرای دستی بسازید؛ سپس همان منطق را به webhook یا زمان‌بندی وصل کنید.
اولین workflow بدون سرویس خارجی
- از بخش Workflows یک workflow جدید بسازید.
- Manual Trigger را اضافه کنید.
- بعد از آن Edit Fields (Set) بگذارید؛ در نسخه‌های قدیمی‌تر نام آن Set است.
- در حالت Manual Mapping، فیلد متنی
promptرا با مقدار «این متن را در یک جمله خلاصه کن: امروز نسخه جدید سامانه منتشر شد.» بسازید. - Execute Workflow را بزنید و خروجی node را در نمای JSON ببینید.
خروجی یک item باید فیلد زیر را داشته باشد:
{
"prompt": "این متن را در یک جمله خلاصه کن: امروز نسخه جدید سامانه منتشر شد."
}
حالا می‌توانید یک node درخواست AI به آن وصل کنید. راهنمای هوش مصنوعی چابکان فایل آمادهٔ همین workflow و تنظیمات credential را دارد.
داده و expression چگونه کار می‌کنند؟
در node معمولی، $json به دادهٔ item ورودی همان node اشاره می‌کند. برای خواندن متن بالا، فیلد مقصد را به حالت Expression ببرید:
{{ $json.prompt }}
اگر HTTP Request به API دیگری وصل شود، خروجی آن معمولاً پاسخ API است؛ فیلدهای ورودی را خودکار در پاسخ پیدا نمی‌کنید. برای خواندن یک node قبلی با نام دقیقش و با حفظ ارتباط itemها می‌توانید استفاده کنید:
{{ $('Edit Fields').item.json.prompt }}
نام داخل عبارت باید با نام node در canvas یکسان باشد. برای مسیر داده از پنل INPUT کمک بگیرید. برای چند item، نتیجهٔ هر item و ارتباط آن با ورودی را جدا بررسی کنید؛ انتخاب ثابت اولین item ممکن است دادهٔ کاربر دیگری را وارد پاسخ کند.
دریافت داده از فرم یا API با Webhook
نمونهٔ ساده: Webhook → Edit Fields → پردازش → Respond to Webhook.
| تنظیم Webhook | مقدار پیشنهادی نمونه |
|---|---|
| HTTP Method | POST |
| Path | text-summary |
| Authentication | Header Auth با credential مستقل برای فراخواننده |
| Respond | Using 'Respond to Webhook' Node |
در Header Auth می‌توانید نام هدر X-Workflow-Key و یک مقدار محرمانه تعیین کنید. این credential با کلید AI چابکان فرق دارد. درخواست باید JSON زیر را بفرستد:
{
"text": "متن موردنظر برای پردازش"
}
در node بعدی، متن webhook را از این مسیر بردارید:
{{ $json.body.text }}
قبل از تماس با AI، با If نوع، خالی‌نبودن و طول متن را بررسی کنید؛ مثلاً فقط متن حداکثر ۴۰۰۰ نویسه را بپذیرید. شاخهٔ نامعتبر را با Respond to Webhook و کد 400 پاسخ دهید. این عدد محدودیت API چابکان نیست، سیاست پیشنهادی همین نمونه است.
در شاخه ٔ معتبر، متن را در فیلد prompt قرار دهید و به HTTP Request هوش مصنوعی بدهید. پاسخ را به فیلد answer تبدیل و با Respond to Webhook در قالب JSON برگردانید. شاخهٔ خطای درخواست هم باید پاسخ کنترل‌شده بدهد؛ درخواست را تا timeout باز نگذارید.
روش‌های پاسخ و احراز هویت در مرجع Webhook n8n توضیح داده شده‌اند.
Test URL با Production URL فرق دارد
برای تست، روی Listen for test event بزنید و درخواست را به Test URL نمایش‌داده‌شده در node بفرستید. برای استفادهٔ دائمی، workflow را Publish/Activate کنید و Production URL را به فراخواننده بدهید. اجراهای واقعی را در Executions بررسی کنید؛ لزوماً روی canvas نمایش داده نمی‌شوند. مرجع چرخهٔ توسعه webhook
آدرس را از node کپی کنید؛ مسیر یا نام سرویس را حدس نزنید. اگر دامنهٔ URL اشتباه است، تنظیمات آدرس عم ومی را اصلاح کنید.
اجرای زمان‌بندی‌شده و رسیدگی به خطا
برای اجرای خودکار دوره‌ای، Manual Trigger را با Schedule Trigger جایگزین و timezone و زمان‌بندی را بررسی کنید. انتشار workflow برای اجرای خودکار لازم است. نمونه‌های کاربردی: گزارش روزانه، همگام‌سازی اطلاعات و خلاصه‌سازی پیام‌های جدید.
برای اعلان خطا، workflow جداگانه‌ای با Error Trigger بسازید و از Workflow Settings ← Error Workflow آن را انتخاب کنید. هشدار را به مقصدی بفرستید که از محل n8n در دسترس باشد؛ هشدار تلگرام روی سرور فاقد دسترسی تلگرام هم شکست می‌خورد. Error Trigger برای اجرای خودکار شکست‌خورده است، نه تست دستی همان workflow. راهنمای Error Trigger
قبل از انتشار، یک ورودی معتبر، یک ورودی نامعتبر و یک خطای کنترل‌شده را آزمایش کنید. retry روی تماس AI با retry روی ارسال پیام یا ثبت سفارش فرق دارد؛ برای عملیات اثرگذار از شناسهٔ یکتای رویداد برای جلوگیری از تک رار استفاده کنید.