آموزش راه‌اندازی n8n در ابربیت و ساخت اولین وب‌هوک

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

در این آموزش، برنامهٔ آمادهٔ n8n را در ابربیت می‌سازیم و یک گردش‌کار کوچک با دو گره تعریف می‌کنیم: دریافت درخواست با Webhook و برگرداندن پاسخ مشخص با Respond to Webhook. مثال به حساب خارجی، ارسال پیام یا دادهٔ واقعی نیاز ندارد؛ ابتدا با دادهٔ ساختگی، مسیر دریافت تا پاسخ را بررسی می‌کنیم.

پیش‌نیاز و محدودهٔ مثال

برای شروع، یک پروژه و دسترسی ساخت برنامه در کنسول ابربیت، ایمیل مدیر و ابزار curl لازم است. سرویس برنامه‌های ابری ابربیت در دورهٔ آزمایشی است؛ پیش از ساخت، منابع، موجودی و برآورد هزینهٔ همان سفارش را بررسی کنید. این آموزش تضمین ظرفیت، دسترس‌پذیری دائمی یا موفقیت اتصال به سرویس‌های بیرونی نیست.

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

مرحلهٔ اول: ساخت برنامه و ورود اولیه

1. ابتدا در کنسول ابربیت، پروژهٔ موردنظر را باز کنید و به بخش پلتفرم و ساخت برنامه بروید.
2. سپس در برنامه‌های آماده، گزینهٔ n8n را انتخاب کنید و نامی مانند my-automation وارد کنید.
3. در فیلد ایمیل مدیر، ایمیلی را بنویسید که برای ورود اولیه استفاده خواهید کرد؛ این ایمیل را درست و در دسترس وارد کنید.
4. پس از بررسی مشخصات و برآورد هزینه، درخواست ساخت را ثبت کنید و تا آماده‌شدن برنامه منتظر بمانید.
5. در جزئیات برنامه، مالک یا مدیر پروژه می‌تواند اطلاعات ورود اولیه را یک‌بار دریافت کند؛ پیش از بستن پنجره، رمز را در محل امن نگه دارید.
6. در پایان، آدرس HTTPS برنامه را باز کنید و با ایمیل انتخاب‌شده و رمز اولیه وارد شوید؛ پس از ورود، رمز را تغییر دهید.

حساب مدیر در فرایند نصب ساخته می‌شود؛ نیازی به ساخت حساب اولیه از صفحهٔ عمومی ندارید. آدرس اصلی خودکار برنامه، نشانی مبنای editor و webhook است؛ افزودن ساب‌دامین دلخواه، این نشانی اصلی را عوض نمی‌کند. برای نمونه‌های زیر، همیشه URL نمایش‌داده‌شده در خود گره Webhook را کپی کنید.

ساخت برنامهٔ n8n در کنسول ابربیت

مرحلهٔ دوم: ساخت گردش‌کار دریافت و پاسخ

در محیط n8n یک گردش‌کار جدید با نامی مانند Webhook demo بسازید. در این مثال دو گره به‌ترتیب به هم متصل می‌شوند:

1. ابتدا گره Webhook را اضافه کنید؛ مقدار HTTP Method را POST و مقدار Path را abrbit-demo بگذارید.
2. برای احراز هویت، گزینهٔ Authentication را Header Auth انتخاب و یک credential تازه بسازید؛ نام هدر را X-Demo-Key و مقدار آن را یک رشتهٔ تصادفی و طولانی قرار دهید. رمز حساب مدیر یا توکن سرویس دیگری را برای این کار استفاده نکنید.
3. در گزینهٔ Respond، حالت Using 'Respond to Webhook' Node را انتخاب کنید تا پاسخ را گره بعدی تعیین کند.
4. سپس گره Respond to Webhook را اضافه و خروجی Webhook را به ورودی آن وصل کنید.
5. در گره پاسخ، گزینهٔ Respond With را JSON بگذارید و مقدار ثابت زیر را در Response Body وارد کنید؛ این مقدار expression نیست. در صورت نیاز، از بخش گزینه‌ها مقدار Response Code را روی 200 قرار دهید.

{
  "received": true,
  "source": "n8n-demo"
}

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

مرحلهٔ سوم: ارسال درخواست آزمایشی

در گره Webhook، بخش Test URL را انتخاب و نشانی کامل را کپی کنید؛ سپس روی Listen for test event بزنید. آدرس آزمایشی فقط هنگام انتظار برای رویداد آزمایشی قابل استفاده است. اگر زمان انتظار تمام شد، دوباره آن را فعال کنید.

در ترمینال Bash، دستور زیر را اجرا کنید؛ در اعلان اول، Test URL واقعی و در اعلان دوم، همان مقدار محرمانهٔ credential هدر را وارد کنید. مقدار کلید روی صفحه نمایش داده نمی‌شود؛ قابلیت ثبت جزئیات شل مانند set -x را روشن نکنید و خروجی یا تصویر حاوی credential را منتشر نکنید.

read -r -p 'Webhook URL: ' webhook_url
read -r -s -p 'Demo key: ' demo_key
printf '\n'
printf 'X-Demo-Key: %s\n' "$demo_key" |
  curl --fail-with-body --silent --show-error --max-time 30 \
    --request POST --header @- \
    --header 'Content-Type: application/json' \
    --data '{"event":"demo","reference":"sample-001"}' \
    "$webhook_url"
unset demo_key webhook_url

با اجرای موفق دو گره، باید همان JSON تعیین‌شده در بخش قبل را دریافت کنید. در بوم n8n نیز ورودی ساختگی و نتیجهٔ اجرای گره‌ها را بررسی کنید. این بدنه نمونهٔ آموزشی است؛ اطلاعات مشتری، رمز یا دادهٔ حساس را برای اولین آزمایش نفرستید.

مرحلهٔ چهارم: انتشار و آدرس عملیاتی

پس از موفقیت آزمایش، گردش‌کار را با گزینهٔ Publish منتشر کنید و این بار Production URL را از گره Webhook بردارید. دستور قبل را با آدرس عملیاتی و همان credential اجرا کنید؛ نشانی را با جایگزین‌کردن دستی بخشی از URL حدس نزنید. آدرس آزمایشی را هم در سرویس مبدأ واقعی ثبت نکنید.

برای مشاهدهٔ اجرای درخواست عملیاتی، بخش Executions را باز کنید؛ انتظار نداشته باشید دادهٔ درخواست عملیاتی مانند حالت تست مستقیماً روی بوم ظاهر شود. پس از تغییر گردش‌کار نیز نسخهٔ موردنظر را دوباره منتشر کنید. تفاوت ثبت آدرس تست و عملیاتی در راهنمای رسمی Webhook توضیح داده شده است.

برای کنترل احراز هویت، یک درخواست با کلید نادرست بفرستید و مطمئن شوید پاسخ موفق نمونه را دریافت نمی‌کنید و اجرای موفقی ثبت نمی‌شود. آدرس وب‌هوک به‌تنهایی جایگزین احراز هویت نیست. اگر بعداً عملیاتی مثل ارسال پیام یا ثبت داده اضافه کردید، تکرار درخواست را هم در طراحی در نظر بگیرید؛ پس از timeout، بدون بررسی نتیجهٔ اجرا درخواست اثرگذار را تکرار نکنید.

داده‌ها، منابع و محدودیت‌های نصب ابربیت

• مشخصات فعلی قالب شامل یک‌ونیم هسته پردازنده و ۱۵۳۶ مگابایت حافظه در مجموع برنامه و runner، همراه یک دیسک پایدار پنج گیگابایتی است؛ مشخصات و هزینهٔ نهایی را در کنسول بررسی کنید.
• داده‌های گردش‌کار، اطلاعات اتصال و تاریخچه در SQLite روی دیسک نصب نگهداری می‌شوند؛ این نگهداری به معنی پشتیبان خودکار نیست. خروجی JSON گردش‌کار هم پشتیبان کامل credentialها و کلید رمزگذاری نصب نیست.
• اجرای نصب تک‌نسخه‌ای است و راه‌اندازی مجدد می‌تواند وقفه ایجاد کند؛ این قالب برای شروع و بار سبک در نظر گرفته شده و مقیاس‌پذیری چندنسخه‌ای یا صف اجرای توزیع‌شده ارائه نمی‌کند.
• اجرای کد JavaScript و Python از طریق runner مجزا در پروفایل قرار دارد؛ اما نصب بستهٔ اضافی، نودهای community، اجرای فرمان سیستم و دسترسی نودها به فایل محلی یا متغیرهای محیطی ارائه نمی‌شوند.
• اتصال به سرویس‌ها به مقصدهای عمومی مجاز اینترنت محدود است؛ شبکهٔ خصوصی، متادیتا، زیرساخت ابربیت و IPv6 در دسترس این قالب نیستند. امکان اتصال به هر API بیرونی را، با توجه به شبکه و مجوزهای همان سرویس، جدا آزمایش کنید.
• حذف برنامه، دیسک و داده‌های همین نصب را برای همیشه حذف می‌کند؛ پیش از حذف، داده‌های موردنیاز را مستقل و امن نگه دارید. هنگام ادامهٔ حذف و آزادسازی دیسک، نتیجه را از وضعیت نهایی عملیات پیگیری کنید.

برای سرویس‌های بیرونی از بخش credentialهای n8n استفاده کنید و رمزها را در متن گره، URL یا فایل خروجی گردش‌کار قرار ندهید. دسترسی و نگهداری تاریخچهٔ اجرا را هم متناسب با حساسیت داده تنظیم کنید؛ ابزار اتوماسیون ممکن است دادهٔ ورودی و خروجی مراحل را در تاریخچه نگه دارد.

رفع خطاهای رایج

• اگر پاسخ 404 گرفتید، روش درخواست، مسیر و تفاوت Test URL با Production URL را بررسی کنید؛ برای تست، شنونده باید فعال باشد و برای مسیر عملیاتی، گردش‌کار باید منتشر شده باشد.
• اگر درخواست احراز هویت نشد، نام هدر و مقدار credential را بررسی کنید؛ رمز ورود به editor همان کلید وب‌هوک نیست.
• اگر پاسخ پیش‌فرض گرفتید یا JSON مورد انتظار برنگشت، اتصال دو گره و گزینهٔ Respond در گره Webhook را بررسی کنید؛ گره پاسخ باید در مسیر اجرا قرار داشته باشد.
• اگر درخواست timeout شد، بخش Executions را ببینید؛ ممکن است پاسخ به کلاینت نرسیده باشد ولی اجرا شروع شده باشد. در گردش‌کارهای اثرگذار، تکرار بی‌بررسی می‌تواند عملیات را دوباره انجام دهد.
• اگر اتصال یک گره به سرویس بیرونی شکست خورد، credential، محدودیت سرویس مقصد و عمومی‌بودن مقصد را بررسی کنید؛ این نصب مسیر دسترسی به دیتابیس خصوصی یا میزبان داخلی شما نیست.

برای جزئیات تنظیم پاسخ می‌توانید راهنمای رسمی Respond to Webhook و برای مدیریت اطلاعات اتصال مستندات credentialها را بخوانید. اگر مشکل مربوط به ساخت یا دسترسی برنامه در ابربیت بود، نام برنامه، زمان رخداد و شرح کوتاه خطا را در تیکت بنویسید؛ رمز، کلید هدر، اطلاعات مشتری و خروجی کامل گردش‌کار را ضمیمه نکنید.

شروع ساخت n8n در ابربیت یا آشنایی با برنامه‌های آمادهٔ ابربیت