نود On App Event در N8N

نود On App Event در N8N

نود On App Event در N8N برای شروع خودکار یک ورکفلو بر اساس رخدادهای یک اپلیکیشن استفاده می‌شود؛ یعنی به‌جای اینکه شما به‌صورت دستی ورکفلو را اجرا کنید، وقوع یک اتفاق در یک سرویس خارجی مثل ساخت یک رکورد جدید، دریافت پیام، ثبت سفارش، تغییر وضعیت یک آیتم یا ایجاد یک تیکت می‌تواند اجرای ورکفلو را آغاز کند.

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

معرفی نود در N8N

On App Event یک نود از نوع Trigger است. وظیفه اصلی آن شروع کردن ورکفلو هنگام وقوع یک رویداد در یک اپلیکیشن یا سرویس متصل است. این رویداد می‌تواند از طریق Webhook، Polling یا API داخلی سرویس موردنظر دریافت شود.

  • نوع نود: Trigger
  • دسته‌بندی: Integration / Trigger
  • کارکرد اصلی: شروع اجرای ورکفلو بر اساس رخدادهای یک اپلیکیشن
  • مناسب برای: اتوماسیون‌های لحظه‌ای، پردازش رویدادها، اتصال سرویس‌ها، دریافت داده جدید از اپلیکیشن‌ها

برای مثال، اگر در یک سیستم CRM یک لید جدید ثبت شود، نود On App Event می‌تواند ورکفلو را فعال کند، اطلاعات لید را دریافت کند، آن را در Google Sheets ذخیره کند، یک پیام در Slack ارسال کند و هم‌زمان یک ایمیل خوشامدگویی برای مشتری بفرستد.

اهمیت این نود در ورکفلوها بسیار زیاد است، چون نقطه شروع بسیاری از اتوماسیون‌های واقعی است. در عمل، بیشتر ورکفلوهای کاربردی با یک Trigger آغاز می‌شوند و On App Event یکی از رایج‌ترین الگوهای شروع ورکفلو در N8N محسوب می‌شود.

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

نود On App Event زمانی کاربرد دارد که بخواهید N8N به تغییرات یا رخدادهای یک اپلیکیشن واکنش نشان دهد. این رخدادها بسته به سرویس متصل‌شده متفاوت هستند؛ مثلا در GitHub می‌تواند Push جدید باشد، در Stripe پرداخت موفق، در Gmail ایمیل جدید، در Notion ایجاد صفحه جدید و در CRM ایجاد یا تغییر مخاطب.

ثبت سفارش جدید در فروشگاه آنلاین

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

  • دریافت سفارش جدید از WooCommerce یا Shopify
  • بررسی مبلغ سفارش با نود IF
  • ثبت اطلاعات سفارش در Google Sheets
  • ارسال پیام اطلاع‌رسانی به تیم فروش در Telegram یا Slack
  • ارسال ایمیل تایید سفارش به مشتری

مدیریت لیدهای جدید در CRM

در تیم‌های فروش، سرعت واکنش به لیدهای جدید اهمیت زیادی دارد. با On App Event می‌توان هر لید جدید را بلافاصله پردازش کرد.

  • شروع ورکفلو با ایجاد Lead جدید در CRM
  • غنی‌سازی داده با استفاده از HTTP Request
  • دسته‌بندی لید با نود Code یا IF
  • ارسال لیدهای مهم به Slack
  • ایجاد تسک پیگیری در Trello، Asana یا ClickUp

پردازش ایمیل‌های جدید

اگر از Gmail، Outlook یا سرویس‌های ایمیلی دیگر استفاده می‌کنید، می‌توانید با دریافت ایمیل جدید، فرایندهای خودکار ایجاد کنید.

  • تشخیص ایمیل جدید
  • فیلتر کردن بر اساس فرستنده یا عنوان
  • استخراج پیوست‌ها
  • ذخیره فایل‌ها در Google Drive
  • ارسال خلاصه ایمیل به یک کانال داخلی

مانیتورینگ رخدادهای فنی

در پروژه‌های نرم‌افزاری، On App Event می‌تواند برای واکنش به رویدادهای GitHub، GitLab، Jira یا ابزارهای DevOps استفاده شود.

  • اجرای ورکفلو هنگام Push جدید در GitHub
  • ارسال پیام به تیم پس از ایجاد Pull Request
  • ایجاد تسک در Jira هنگام ثبت Issue جدید
  • ثبت لاگ رخدادها در دیتابیس
  • ارسال هشدار برای رخدادهای بحرانی

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

نود On App Event معمولا به‌تنهایی استفاده نمی‌شود و ارزش اصلی آن در ترکیب با سایر نودهای N8N مشخص می‌شود.

  • IF: برای بررسی شرط‌ها و جداسازی مسیرهای مختلف
  • Switch: برای مسیردهی بر اساس نوع رخداد
  • Set / Edit Fields: برای مرتب‌سازی و آماده‌سازی داده‌ها
  • Code: برای پردازش پیشرفته داده‌ها با JavaScript
  • HTTP Request: برای ارسال داده به APIهای خارجی
  • Google Sheets: برای ذخیره‌سازی داده‌ها در فایل‌های جدولی
  • Slack / Telegram / Discord: برای ارسال اعلان
  • Database Nodes: برای ذخیره داده در PostgreSQL، MySQL، MongoDB و سایر دیتابیس‌ها

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

پارامترهای دقیق نود On App Event به اپلیکیشن انتخاب‌شده بستگی دارد. چون هر سرویس رخدادها، احراز هویت و تنظیمات مخصوص خود را دارد. با این حال، بیشتر نودهای On App Event در N8N چند بخش تنظیماتی مشترک دارند که در ادامه توضیح داده می‌شوند.

Credentials

  • نام پارامتر: Credentials
  • نوع داده: Credential / Authentication Object
  • کاربرد: اتصال امن N8N به سرویس خارجی
  • مثال عملی: اتصال به حساب GitHub با Personal Access Token یا اتصال به Google با OAuth2

در این بخش باید اطلاعات دسترسی به سرویس موردنظر را وارد کنید. نوع احراز هویت می‌تواند API Key، OAuth2، Bearer Token، Basic Auth یا روش اختصاصی سرویس باشد.

Event

  • نام پارامتر: Event
  • نوع داده: Options / String
  • کاربرد: تعیین نوع رخدادی که باعث اجرای ورکفلو می‌شود
  • مثال عملی: New Order، New Contact، Payment Succeeded، New Email، Issue Created

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

Resource

  • نام پارامتر: Resource
  • نوع داده: Options / String
  • کاربرد: تعیین منبع یا موجودیتی که رویداد مربوط به آن است
  • مثال عملی: Order، Customer، Contact، Issue، Message، File

در برخی نودها ابتدا باید Resource را انتخاب کنید. مثلا در یک سرویس فروشگاهی، Resource می‌تواند Order یا Customer باشد. سپس در بخش Event تعیین می‌کنید روی همان Resource چه رخدادی مدنظر است.

Trigger On

  • نام پارامتر: Trigger On
  • نوع داده: Options
  • کاربرد: مشخص کردن شرایط فعال شدن تریگر
  • مثال عملی: فعال شدن هنگام ایجاد رکورد جدید یا هنگام به‌روزرسانی رکورد موجود

در بعضی اپلیکیشن‌ها، به‌جای Event از گزینه‌هایی مثل Trigger On استفاده می‌شود. این گزینه تعیین می‌کند نود روی چه عملیاتی حساس باشد.

Poll Times

  • نام پارامتر: Poll Times
  • نوع داده: Schedule / Interval
  • کاربرد: تعیین زمان‌بندی بررسی رخدادهای جدید در حالت Polling
  • مثال عملی: بررسی هر ۵ دقیقه برای دریافت ایمیل‌های جدید

اگر سرویس موردنظر Webhook واقعی ارائه ندهد، N8N ممکن است با روش Polling کار کند. در این حالت، نود در بازه‌های زمانی مشخص API سرویس را بررسی می‌کند تا رویدادهای جدید را پیدا کند.

Webhook URL

  • نام پارامتر: Webhook URL
  • نوع داده: URL
  • کاربرد: آدرسی که سرویس خارجی برای ارسال رخدادها به N8N استفاده می‌کند
  • مثال عملی: آدرس تولیدشده توسط N8N برای دریافت رخدادهای Stripe یا GitHub

در نودهای مبتنی بر Webhook، N8N یک آدرس مخصوص ایجاد می‌کند. این آدرس باید در سرویس خارجی ثبت شود یا N8N به‌صورت خودکار آن را هنگام فعال‌سازی ورکفلو ثبت می‌کند.

Filters

  • نام پارامتر: Filters
  • نوع داده: Object / Options / String
  • کاربرد: محدود کردن رویدادهای دریافتی بر اساس شرایط مشخص
  • مثال عملی: دریافت فقط سفارش‌هایی که وضعیت آن‌ها Paid است یا فقط ایمیل‌هایی که از یک دامنه خاص ارسال شده‌اند

فیلترها باعث می‌شوند داده‌های غیرضروری وارد ورکفلو نشوند. این کار هم سرعت اجرای ورکفلو را افزایش می‌دهد و هم تعداد اجرای‌های بی‌مورد را کاهش می‌دهد.

Additional Fields

  • نام پارامتر: Additional Fields
  • نوع داده: Object
  • کاربرد: تنظیم گزینه‌های تکمیلی اختصاصی هر سرویس
  • مثال عملی: انتخاب Label در Gmail، انتخاب Repository در GitHub یا انتخاب Pipeline در CRM

در بسیاری از نودها، تنظیمات اختصاصی سرویس در بخش Additional Fields قرار دارد. این بخش برای کنترل دقیق‌تر رفتار تریگر استفاده می‌شود.

Include Headers

  • نام پارامتر: Include Headers
  • نوع داده: Boolean
  • کاربرد: مشخص کردن اینکه هدرهای درخواست ورودی نیز در خروجی نود قرار بگیرند یا خیر
  • مثال عملی: استفاده از هدر امضای امنیتی برای اعتبارسنجی رخدادهای دریافتی

این گزینه در نودهایی که داده را از Webhook دریافت می‌کنند مفید است. مثلا بعضی سرویس‌ها برای تایید اصالت درخواست، امضا یا شناسه رخداد را در Header ارسال می‌کنند.

Include Raw Data

  • نام پارامتر: Include Raw Data
  • نوع داده: Boolean
  • کاربرد: دریافت داده خام ارسال‌شده توسط سرویس خارجی
  • مثال عملی: ذخیره Payload اصلی Stripe برای بررسی‌های بعدی

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

Limit

  • نام پارامتر: Limit
  • نوع داده: Number
  • کاربرد: تعیین حداکثر تعداد آیتم‌هایی که در هر اجرای Polling دریافت می‌شوند
  • مثال عملی: دریافت حداکثر ۵۰ ایمیل جدید در هر بار بررسی

در تریگرهای مبتنی بر Polling، مقدار Limit به کنترل حجم داده کمک می‌کند. اگر مقدار خیلی بالا انتخاب شود، ممکن است ورکفلو سنگین شود یا با محدودیت API مواجه شوید.

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

  • در حالت Webhook، ورکفلو باید Active باشد تا رخدادهای واقعی را دریافت کند.
  • در حالت Test، ممکن است فقط داده آزمایشی دریافت شود و رفتار با حالت Production متفاوت باشد.
  • اگر سرویس خارجی از OAuth2 استفاده می‌کند، دسترسی‌ها یا Scopeهای لازم باید فعال باشند.
  • در سرویس‌های دارای Rate Limit، Polling با فاصله زمانی کوتاه می‌تواند باعث خطا شود.
  • فرمت تاریخ و زمان معمولا به‌صورت ISO 8601 است، مانند 2025-01-15T10:30:00Z.
  • در رخدادهای پرداخت و مالی، بهتر است شناسه رخداد برای جلوگیری از پردازش تکراری ذخیره شود.
  • اگر چند ورکفلو از یک رویداد مشابه استفاده می‌کنند، احتمال دریافت تکراری داده یا ایجاد بار اضافی روی API وجود دارد.

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

نود On App Event معمولا ورودی مستقیم از نود قبلی ندارد، چون به‌عنوان نقطه شروع ورکفلو عمل می‌کند. داده ورودی آن از اپلیکیشن خارجی، Webhook یا API سرویس دریافت می‌شود.

ورودی نود

از نظر ساختار ورکفلو، این نود معمولا Input ندارد. اما از نظر داده‌ای، ورودی آن همان Payload رخداد ارسالی از اپلیکیشن است.

  • در حالت Webhook: داده از طرف سرویس خارجی به URL تولیدشده توسط N8N ارسال می‌شود.
  • در حالت Polling: N8N در بازه‌های زمانی مشخص سرویس را بررسی کرده و آیتم‌های جدید را دریافت می‌کند.
  • در حالت Event API: نود با API سرویس هماهنگ می‌شود و رخدادهای قابل دریافت را واکشی می‌کند.

خروجی نود

خروجی نود شامل اطلاعات رخداد، داده اصلی مربوط به آن، شناسه‌ها، زمان رخداد و گاهی اطلاعات اضافی مثل Header، Metadata یا Raw Payload است.

نمونه خروجی JSON

{  "event": "order.created",  "id": "evt_123456789",  "createdAt": "2025-01-15T10:30:00Z",  "data": {    "orderId": "ORD-10025",    "customer": {      "id": "CUS-7788",      "name": "Ali Rezaei",      "email": "ali@example.com"    },    "amount": 2450000,    "currency": "IRR",    "status": "paid",    "items": [      {        "sku": "PRD-001",        "title": "Online Course",        "quantity": 1,        "price": 2450000      }    ]  },  "metadata": {    "source": "shop",    "triggerType": "webhook"  }}

جدول ساختار خروجی متداول

فیلدنوع دادهتوضیحمثال
eventStringنوع رخداد دریافت‌شدهorder.created
idStringشناسه یکتای رخدادevt_123456789
createdAtString / Dateزمان وقوع رخداد2025-01-15T10:30:00Z
dataObjectداده اصلی مربوط به رخداداطلاعات سفارش، کاربر، پیام یا رکورد
metadataObjectاطلاعات تکمیلی درباره منبع و نحوه دریافتsource، triggerType
headersObjectهدرهای درخواست، در صورت فعال بودنx-signature، user-agent

استفاده از داده خروجی در نودهای بعدی

برای دسترسی به داده‌های خروجی در نودهای بعدی می‌توان از Expressionهای N8N استفاده کرد.

{{$json.data.customer.email}}

مثال‌های کاربردی:

  • دریافت ایمیل مشتری: {{$json.data.customer.email}}
  • دریافت مبلغ سفارش: {{$json.data.amount}}
  • دریافت وضعیت پرداخت: {{$json.data.status}}
  • دریافت شناسه رخداد: {{$json.id}}

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

جلوگیری از پردازش تکراری رخدادها

بعضی سرویس‌ها ممکن است یک رخداد را بیش از یک‌بار ارسال کنند، مخصوصا اگر پاسخ مناسب از Webhook دریافت نکنند. برای جلوگیری از پردازش تکراری، شناسه رخداد را در دیتابیس یا Data Store ذخیره کنید و قبل از ادامه ورکفلو بررسی کنید که قبلا پردازش نشده باشد.

  • دریافت eventId از خروجی نود
  • جستجو در Data Store یا دیتابیس
  • اگر قبلا وجود داشت، توقف ورکفلو
  • اگر جدید بود، ادامه پردازش و ذخیره شناسه رخداد

اعتبارسنجی درخواست‌های Webhook

در رخدادهای مهم مانند پرداخت، بهتر است امضای درخواست بررسی شود. بسیاری از سرویس‌ها یک Signature در Header ارسال می‌کنند. با استفاده از نود Code یا Crypto می‌توانید Payload و Signature را اعتبارسنجی کنید.

const signature = $json.headers["x-signature"];const payload = JSON.stringify($json.body);return [  {    json: {      isValid: Boolean(signature),      signature,      payload    }  }];

استفاده از IF برای فیلتر کردن داده‌ها

اگر نمی‌خواهید همه رخدادها پردازش شوند، بعد از On App Event از نود IF استفاده کنید. مثلا فقط سفارش‌هایی را ادامه دهید که مبلغ آن‌ها بیشتر از مقدار مشخصی است.

  • شرط: {{$json.data.amount}} بزرگ‌تر از 1000000
  • مسیر True: ارسال به تیم فروش
  • مسیر False: فقط ذخیره در دیتابیس

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

اگر یک نود چند نوع Event دریافت می‌کند، با نود Switch می‌توانید مسیرهای مختلف ایجاد کنید.

  • order.created → ثبت سفارش جدید
  • order.paid → ارسال فاکتور
  • order.cancelled → اطلاع‌رسانی به پشتیبانی
  • customer.created → ثبت مخاطب در CRM

بهینه‌سازی Polling

در نودهایی که با Polling کار می‌کنند، زمان‌بندی مناسب اهمیت زیادی دارد. بررسی بیش‌ازحد سریع می‌تواند باعث مصرف زیاد API و خطای Rate Limit شود. بررسی خیلی کند نیز ممکن است باعث تأخیر در پردازش داده‌ها شود.

  • برای داده‌های حساس: هر ۱ تا ۵ دقیقه
  • برای گزارش‌ها و داده‌های عادی: هر ۱۵ تا ۳۰ دقیقه
  • برای داده‌های کم‌اهمیت: هر چند ساعت یک‌بار

ذخیره Raw Payload برای دیباگ

در پروژه‌های مهم، بهتر است داده خام رخداد را در یک دیتابیس یا سیستم لاگ ذخیره کنید. این کار هنگام بررسی خطاها، اختلاف داده و مشکلات ارتباطی بسیار مفید است.

استفاده از Error Workflow

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

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

محدودیت‌های رایج

  • همه اپلیکیشن‌ها از Webhook لحظه‌ای پشتیبانی نمی‌کنند و بعضی فقط با Polling کار می‌کنند.
  • در حالت Polling، اجرای ورکفلو کاملا لحظه‌ای نیست و به بازه زمانی تنظیم‌شده بستگی دارد.
  • برخی سرویس‌ها محدودیت تعداد درخواست API دارند.
  • بعضی رخدادها فقط در پلن‌های پولی سرویس خارجی در دسترس هستند.
  • اگر ورکفلو Active نباشد، در بیشتر موارد رخدادهای واقعی دریافت نمی‌شوند.
  • تغییر در ساختار API سرویس خارجی ممکن است خروجی نود را تغییر دهد.
  • برخی سرویس‌ها رخدادهای قدیمی را دوباره ارسال نمی‌کنند؛ بنابراین اگر ورکفلو غیرفعال باشد، ممکن است داده‌هایی از دست بروند.

خطای احراز هویت

نمونه خطا: Unauthorized، Invalid credentials، 401

علت: Credential اشتباه است، Token منقضی شده یا دسترسی لازم وجود ندارد.

راه‌حل:

  • Credential را دوباره بررسی و ذخیره کنید.
  • در صورت استفاده از OAuth2، اتصال را مجددا انجام دهید.
  • Scopeهای لازم را در سرویس خارجی فعال کنید.
  • اگر از API Key استفاده می‌کنید، مطمئن شوید کلید هنوز معتبر است.

خطای عدم دریافت رویداد

نمونه خطا: ورکفلو اجرا نمی‌شود یا تریگر داده‌ای دریافت نمی‌کند.

علت: ورکفلو فعال نیست، Webhook در سرویس خارجی ثبت نشده یا رویداد انتخاب‌شده رخ نداده است.

راه‌حل:

  • وضعیت Active بودن ورکفلو را بررسی کنید.
  • Webhook URL را در سرویس خارجی بررسی کنید.
  • یک رخداد تستی در سرویس ایجاد کنید.
  • در صورت وجود حالت Test و Production، مطمئن شوید URL درست استفاده شده است.

خطای Rate Limit

نمونه خطا: Too Many Requests، 429

علت: تعداد درخواست‌ها به API سرویس خارجی زیاد است.

راه‌حل:

  • فاصله Polling را بیشتر کنید.
  • Limit تعداد آیتم‌های دریافتی را کاهش دهید.
  • از فیلترهای دقیق‌تر استفاده کنید.
  • در صورت نیاز، پلن API سرویس خارجی را ارتقا دهید.

خطای داده نامعتبر

نمونه خطا: Cannot read property، Undefined value، Invalid JSON

علت: ساختار داده خروجی با چیزی که در نودهای بعدی انتظار دارید متفاوت است.

راه‌حل:

  • خروجی واقعی نود را در Execution بررسی کنید.
  • قبل از استفاده از فیلدها، وجود آن‌ها را با IF بررسی کنید.
  • از Optional Chaining در نود Code استفاده کنید.
  • Expressionها را بر اساس ساختار واقعی داده اصلاح کنید.

خطای دریافت رویداد تکراری

نمونه خطا: یک سفارش یا پیام چند بار پردازش می‌شود.

علت: سرویس خارجی رخداد را مجددا ارسال کرده یا Polling داده را دوباره دریافت کرده است.

راه‌حل:

  • شناسه رخداد یا شناسه رکورد را ذخیره کنید.
  • قبل از پردازش، تکراری نبودن داده را بررسی کنید.
  • در دیتابیس روی شناسه رخداد Unique Constraint قرار دهید.

ایده ها

  • سیستم اعلان هوشمند فروش: با ثبت هر سفارش جدید، مبلغ و نوع محصول بررسی شود و اگر سفارش مهم بود، پیام فوری برای مدیر فروش ارسال شود.
  • اتوماسیون پشتیبانی مشتری: هنگام ایجاد تیکت جدید، اولویت آن تشخیص داده شود و بر اساس کلمات کلیدی به تیم مناسب ارجاع داده شود.
  • مانیتورینگ پرداخت‌ها: با رخداد پرداخت موفق یا ناموفق، فاکتور تولید شود، وضعیت کاربر تغییر کند و گزارش مالی به‌روزرسانی شود.
  • مدیریت محتوای خودکار: با ایجاد صفحه جدید در Notion یا Airtable، محتوا بررسی و برای انتشار در سایت یا شبکه‌های اجتماعی آماده شود.
  • اتوماسیون DevOps: با ایجاد Pull Request یا Issue جدید در GitHub، پیام در Slack ارسال شود و تسک مرتبط در ابزار مدیریت پروژه ساخته شود.

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

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

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

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

3 × 5 =