نانوپ
مستندات n8n
74+ نود

مستندات n8n

74+ نود مستند شده · ۰ بازدید

🔗

وب‌هوک

Webhook

دریافت درخواست HTTP و فعال‌سازی workflow به عنوان Trigger اصلی n8n

ابزارهای توسعه
مقدماتی
۰ بازدید
n8n 1.0+

نمای کلی

نود Webhook مهم‌ترین و اساسی‌ترین Trigger نود در n8n است. این نود یک URL اختصاصی HTTP ایجاد می‌کند که هر زمان درخواستی به آن ارسال شود، workflow مربوطه فعال می‌شود. بدون Webhook، بسیاری از اتوماسیون‌های مبتنی بر رویداد غیرممکن خواهند بود.

قابلیت‌های کلیدی:

  • پشتیبانی از متدهای HTTP: GET, POST, PUT, DELETE, PATCH, HEAD
  • احراز هویت: None (عمومی)، Basic Auth، Header Auth، JWT
  • حالت‌های پاسخ‌دهی: فوری (Immediately)، آخرین نود (Last Node)، پاسخ سفارشی (Respond to Webhook)
  • دریافت و پردازش Binary Data (فایل‌ها)
  • دسترسی به Query Parameters، Headers و Path Parameters
  • دو نوع URL: Test URL (برای توسعه) و Production URL (برای استفاده واقعی)
  • تنظیمات CORS برای درخواست‌های Cross-Origin
  • امکان IP Whitelisting برای افزایش امنیت

تفاوت Test URL و Production URL:

  • Test URL: فقط در حالت Test Workflow فعال است. برای توسعه و دیباگ استفاده می‌شود. پس از بستن تست غیرفعال می‌شود.
  • Production URL: فقط وقتی Workflow فعال (Active) باشد کار می‌کند. برای استفاده واقعی و اتصال سرویس‌های خارجی.

تفاوت با HTTP Request Node:

  • Webhook: منتظر دریافت درخواست از خارج می‌ماند (منفعل/Passive) - یک Trigger است
  • HTTP Request: درخواست را به سرویس خارجی ارسال می‌کند (فعال/Active) - یک Action است

چرا Webhook مهم‌ترین Trigger است؟

بسیاری از سرویس‌ها و پلتفرم‌ها (درگاه‌های پرداخت، GitHub، GitLab، فروشگاه‌های آنلاین، CRM، سیستم‌های مانیتورینگ) رویدادهای خود را از طریق HTTP Webhook اطلاع‌رسانی می‌کنند. بدون این نود، ارتباط بلادرنگ با اکثر سیستم‌ها ممکن نیست.

احراز هویت

احراز هویت Webhook

1. بدون احراز هویت (None)

ساده‌ترین حالت. URL عمومی است و هر کسی می‌تواند آن را فراخوانی کند.

  • مناسب برای تست و webhookهای عمومی
  • برای سرویس‌هایی که خودشان امنیت دارند (مثل GitHub Webhook Secret)
code
https://your-n8n.example.com/webhook/abc-123-def

2. Basic Auth

احراز هویت با Username و Password. کلاینت باید هدر Authorization را ارسال کند:

code
Authorization: Basic base64(username:password)

تنظیم در n8n:

  1. 1Authentication: Basic Auth
  2. 2در Credential: Username و Password را وارد کنید
  3. 3n8n خودکار هدر Authorization را بررسی می‌کند

مثال فراخوانی با curl:

bash
curl -u myuser:mypass https://your-n8n.example.com/webhook/my-path

3. Header Auth

بررسی یک Header سفارشی با مقدار مشخص:

code
X-API-Key: your-secret-api-key-here

تنظیم در n8n:

  1. 1Authentication: Header Auth
  2. 2در Credential: Header Name و Expected Value وارد کنید
  3. 3هر درخواست بدون هدر صحیح رد می‌شود

4. JWT (JSON Web Token)

برای سناریوهای پیشرفته‌تر، می‌توانید JWT را در Code node بعد از Webhook اعتبارسنجی کنید:

javascript
const token = $json.headers.authorization?.replace('Bearer ', '');
// اعتبارسنجی JWT token

نکات امنیتی:

  • برای webhookهای حیاتی (پرداخت، احراز هویت) حتماً از Header Auth یا Basic Auth استفاده کنید
  • URL webhook به تنهایی امنیت کافی نیست - حتی اگر طولانی و تصادفی باشد
  • HTTPS را همیشه فعال کنید تا داده‌ها رمزنگاری شوند
  • از IP Whitelisting در Reverse Proxy (nginx/Caddy) استفاده کنید

عملیات‌های موجود

1

receivePostData

دریافت داده JSON یا Form Data از طریق متد POST. رایج‌ترین حالت استفاده از Webhook.

2

receiveGetRequest

دریافت درخواست GET با Query Parameters. مناسب برای verificationها و callbackهای ساده.

3

handleFileUpload

دریافت فایل‌های باینری از طریق multipart/form-data. مناسب برای آپلود تصویر، PDF و غیره.

4

customResponse

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

5

waitForWebhook

توقف workflow تا دریافت درخواست Webhook. مناسب برای تایید کاربر یا callback پرداخت.

6

handleFormSubmission

دریافت و پردازش داده فرم HTML (application/x-www-form-urlencoded یا multipart/form-data).

7

apiEndpoint

ایجاد endpoint اختصاصی REST API با Webhook. مناسب برای ساخت Microservice.

8

multiMethodHandling

پاسخ به چندین متد HTTP در یک Webhook با استفاده از ALL یا Switch بر اساس متد.

9

binaryResponse

ارسال فایل (تصویر، PDF، ZIP) به عنوان پاسخ Webhook. مناسب برای API تولید فایل.

10

corsConfiguration

تنظیم Cross-Origin Resource Sharing برای فراخوانی از مرورگر و فرانت‌اند.

11

pathParameters

استفاده از پارامترهای داینامیک در مسیر webhook مثل :id یا :action.

12

rawBody

دریافت بدنه خام درخواست بدون پارس شدن. مناسب برای HMAC signature verification.

کاربردهای متداول

کاربردهای رایج

۱. Callback درگاه پرداخت (ZarinPal / IDPay)

پس از پرداخت موفق، درگاه کاربر را به URL callback هدایت می‌کند:

code
Webhook (GET: /payment/verify)
  → Set (Authority = query.Authority, Status = query.Status)
  → IF (Status == "OK")
    → HTTP Request (POST: ZarinPal Verify API)
      Body: { merchant_id, authority, amount }
    → IF (verified)
      → MySQL (به‌روزرسانی وضعیت سفارش)
      → Telegram (اعلان پرداخت موفق)
      → Respond to Webhook (redirect به صفحه موفقیت)
    → Else: Respond to Webhook (redirect به صفحه خطا)

۲. دریافت Webhook از GitHub

اعلان push، pull request، issue و سایر رویدادهای مخزن:

code
Webhook (POST: /github-events)
  Authentication: Header Auth (X-Hub-Signature-256)
  → Switch (بر اساس headers.x-github-event)
    → push: Telegram (اعلان push جدید به تیم)
    → pull_request: MySQL (ثبت PR) + Telegram
    → issues: Telegram (اعلان issue جدید)
    → release: Telegram (اعلان نسخه جدید)

۳. دریافت فرم وب‌سایت (Contact Form)

پردازش فرم تماس یا ثبت‌نام از سایت:

code
Webhook (POST: /contact-form)
  → Set (name, email, phone, message)
  → IF (email معتبر AND phone معتبر)
    → MySQL (ذخیره در دیتابیس)
    → Email (ارسال تایید به کاربر)
    → Telegram (اعلان به تیم پشتیبانی)
    → Respond to Webhook (200: "پیام شما دریافت شد")
  → Else: Respond to Webhook (400: "اطلاعات نامعتبر")

۴. دریافت داده از دستگاه‌های IoT

سنسورها و دستگاه‌های هوشمند داده‌ها را به webhook ارسال می‌کنند:

code
Webhook (POST: /iot/sensor-data)
  Authentication: Header Auth (X-Device-Key)
  → Set (deviceId, temperature, humidity, timestamp)
  → MySQL (ذخیره داده سنسور)
  → IF (temperature > 40 OR humidity > 90)
    → Telegram (هشدار: مقدار غیرعادی سنسور!)
  → Respond to Webhook (200: "received")

۵. یکپارچه‌سازی با CRM

دریافت رویدادهای CRM مثل ثبت مشتری جدید یا تغییر وضعیت معامله:

code
Webhook (POST: /crm/deal-update)
  → Switch (بر اساس event_type)
    → deal_won:
      → MySQL (به‌روزرسانی وضعیت)
      → Email (فاکتور به مشتری)
      → Telegram (تبریک به تیم فروش)
    → deal_lost:
      → MySQL (ثبت دلیل از دست دادن)
      → Telegram (گزارش به مدیر فروش)
    → new_lead:
      → MySQL (ثبت سرنخ جدید)
      → Telegram (اعلان به تیم فروش)

۶. اعلان سفارش فروشگاه آنلاین (WooCommerce / Shopify)

دریافت سفارش جدید از فروشگاه:

code
Webhook (POST: /shop/new-order)
  → Set (فرمت فارسی سفارش)
  → MySQL (ذخیره سفارش)
  → Telegram (sendMessage)
    Text: "سفارش جدید #{{$json.order_id}}
    مشتری: {{$json.customer_name}}
    مبلغ: {{$json.total}} تومان"
  → Email (ایمیل تایید سفارش)
  → Respond to Webhook (200)

۷. هشدارهای مانیتورینگ (Grafana / Prometheus / UptimeRobot)

دریافت alertها از سیستم‌های مانیتورینگ:

code
Webhook (POST: /alerts/monitoring)
  → Switch (بر اساس severity)
    → critical:
      → Telegram (هشدار فوری با ایموجی قرمز)
      → Email (اعلان به تیم DevOps)
      → HTTP Request (ریستارت سرویس خودکار)
    → warning:
      → Telegram (هشدار با ایموجی زرد)
    → resolved:
      → Telegram (اعلان حل شدن مشکل)

۸. Backend چت‌بات

ساخت API برای چت‌بات وب‌سایت یا اپلیکیشن:

code
Webhook (POST: /chatbot/message)
  Authentication: Header Auth
  → Set (userId, message, sessionId)
  → Switch (بر اساس intent تشخیص داده شده)
    → سوال قیمت: MySQL (استعلام قیمت) → پاسخ
    → وضعیت سفارش: MySQL (بررسی سفارش) → پاسخ
    → پشتیبانی: ایجاد تیکت → پاسخ
  → Respond to Webhook (JSON پاسخ چت‌بات)

۹. API Gateway ساده

ساخت API برای اپلیکیشن موبایل یا فرانت‌اند:

code
Webhook (ALL: /api/v1/products)
  Authentication: Header Auth (X-API-Key)
  → Switch (بر اساس $json.method)
    → GET: MySQL (لیست محصولات) → Respond (JSON)
    → POST: MySQL (ثبت محصول) → Respond (201: created)
    → PUT: MySQL (به‌روزرسانی) → Respond (200: updated)
    → DELETE: MySQL (حذف) → Respond (204)

۱۰. Trigger خط لوله CI/CD

فعال‌سازی workflow توسط GitLab CI یا GitHub Actions پس از deploy:

code
Webhook (POST: /ci/deploy-complete)
  Authentication: Header Auth
  → Set (branch, commit, environment, status)
  → IF (status == "success")
    → Telegram (اعلان deploy موفق)
    → HTTP Request (بررسی health سرویس)
    → MySQL (ثبت تاریخچه deploy)
  → Else:
    → Telegram (هشدار: deploy ناموفق!)
    → Email (لاگ خطا به تیم)

۱۱. دریافت Webhook از GitLab

مدیریت رویدادهای مخزن GitLab:

code
Webhook (POST: /gitlab-hook)
  Authentication: Header Auth (X-Gitlab-Token)
  → Switch (بر اساس object_kind)
    → push: اعلان commit جدید
    → merge_request: بررسی و اعلان MR
    → pipeline: اعلان وضعیت pipeline
    → tag_push: اعلان تگ جدید

۱۲. سیستم تایید دو مرحله‌ای

ایجاد لینک تایید برای کاربران:

code
Workflow اول:
  → تولید token تایید
  → Email (لینک: https://n8n.example.com/webhook/verify?token=xxx)

Webhook (GET: /verify)
  → Set (token = query.token)
  → MySQL (بررسی و اعتبارسنجی token)
  → IF (valid)
    → MySQL (فعال‌سازی حساب)
    → Respond to Webhook (HTML: "حساب شما فعال شد!")
  → Else: Respond to Webhook (400: "لینک نامعتبر")

نکات حرفه‌ای

نکات حرفه‌ای

۱. همیشه از Production URL استفاده کنید

Test URL فقط برای توسعه است. برای اتصال سرویس‌های واقعی، Workflow را Active کنید و از Production URL استفاده نمایید.

۲. Response Mode را درست انتخاب کنید

  • Immediately: فوراً پاسخ 200 می‌دهد (بهترین برای callbackهای پرداخت و سرویس‌هایی که timeout کوتاه دارند)
  • When Last Node Finishes: بعد از اتمام workflow پاسخ می‌دهد (برای APIهایی که نتیجه لازم دارند)
  • Using Respond to Webhook Node: پاسخ سفارشی با هدر و بدنه دلخواه (حرفه‌ای‌ترین)

۳. دسترسی به اجزای درخواست

javascript
// بدنه درخواست (POST body)
{{$json.body}}

// Query Parameters (GET ?key=value)
{{$json.query.key}}

// Headers
{{$json.headers['content-type']}}
{{$json.headers['x-api-key']}}

// متد HTTP (وقتی از ALL استفاده می‌کنید)
{{$json.method}}

// Path Parameters
{{$json.params.id}}

// IP فراخوان
{{$json.headers['x-forwarded-for']}}

۴. پاسخ سفارشی با Respond to Webhook

برای ارسال پاسخ کامل سفارشی:

code
Webhook (Response Mode: Using Respond to Webhook Node)
  → پردازش داده‌ها
  → Respond to Webhook
    Response Code: 200
    Response Body: { "status": "success", "data": ... }
    Response Headers:
      Content-Type: application/json
      X-Custom-Header: value

۵. امنیت webhook را جدی بگیرید

  • حتماً از Authentication (Header Auth یا Basic Auth) استفاده کنید
  • برای سرویس‌هایی مثل GitHub از Webhook Secret و HMAC Signature استفاده کنید
  • IP Whitelisting در Reverse Proxy تنظیم کنید
  • HTTPS اجباری باشد
  • داده ورودی را همیشه validate کنید

۶. تست webhook با curl

bash
# تست ساده POST
curl -X POST https://n8n.example.com/webhook/test-path \
  -H "Content-Type: application/json" \
  -d '{"name":"test","value":123}'

# تست با Header Auth
curl -X POST https://n8n.example.com/webhook/secure-path \
  -H "Content-Type: application/json" \
  -H "X-API-Key: my-secret-key" \
  -d '{"event":"order.created"}'

# تست GET با Query Params
curl "https://n8n.example.com/webhook/verify?token=abc&status=OK"

# تست آپلود فایل
curl -X POST https://n8n.example.com/webhook/upload \
  -F "file=@/path/to/document.pdf" \
  -F "description=فاکتور فروش"

# تست Basic Auth
curl -u admin:secretpass https://n8n.example.com/webhook/protected

۷. HMAC Signature Verification

برای سرویس‌هایی مثل GitHub و Stripe که signature ارسال می‌کنند:

javascript
// در Code node بعد از Webhook
const crypto = require('crypto');
const secret = 'your-webhook-secret';
const payload = JSON.stringify($json.body);
const signature = $json.headers['x-hub-signature-256'];
const expected = 'sha256=' + crypto
  .createHmac('sha256', secret)
  .update(payload)
  .digest('hex');
if (signature !== expected) throw new Error('Invalid signature');

۸. مدیریت Idempotency

از تکرار پردازش جلوگیری کنید:

code
Webhook → Set (eventId = body.event_id)
  → MySQL (SELECT WHERE event_id = ?)
  → IF (قبلاً پردازش نشده)
    → پردازش اصلی
    → MySQL (INSERT event_id)
  → Else: Respond (200: "already processed")

۹. Multi-Method API با Switch

code
Webhook (ALL: /api/resource)
  → Switch (بر اساس {{$json.method}})
    → GET: خواندن از دیتابیس → Respond (لیست)
    → POST: ذخیره در دیتابیس → Respond (201)
    → PUT: به‌روزرسانی → Respond (200)
    → DELETE: حذف → Respond (204)

۱۰. Webhook URL را از Environment Variable بگیرید

code
N8N_HOST=n8n.example.com
WEBHOOK_URL=https://n8n.example.com/
N8N_PROTOCOL=https
N8N_PORT=5678

۱۱. پاسخ HTML برای Redirect

javascript
// در Respond to Webhook
Response Code: 302
Response Headers:
  Location: https://mysite.com/success?order=123
// یا پاسخ HTML:
Response Body: "<html><body>با تشکر! <a href='https://mysite.com'>بازگشت</a></body></html>"
Content-Type: text/html

۱۲. لاگ تمام درخواست‌های ورودی

برای Debug و مانیتورینگ:

code
Webhook → Code (لاگ جزئیات)
  console.log('Method:', $json.method);
  console.log('Headers:', JSON.stringify($json.headers));
  console.log('Body:', JSON.stringify($json.body));
  console.log('Query:', JSON.stringify($json.query));
  → ادامه workflow

۱۳. مدیریت خطا در webhook workflow

code
Webhook
  → Error Trigger (on error in workflow)
    → Telegram (اعلان خطا به ادمین)
    → Respond to Webhook (500: "Internal Error")
// یا از try/catch در Code node استفاده کنید

۱۴. تنظیمات nginx برای Webhook

nginx
location /webhook/ {
    proxy_pass http://localhost:5678/webhook/;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;
    client_max_body_size 50m;
}

۱۵. Rate Limiting در Reverse Proxy

برای جلوگیری از حمله DDoS به webhook:

nginx
limit_req_zone $binary_remote_addr zone=webhook:10m rate=10r/s;
location /webhook/ {
    limit_req zone=webhook burst=20 nodelay;
    proxy_pass http://localhost:5678/webhook/;
}

۱۶. Webhook برای چندین Environment

از path متفاوت برای محیط‌های مختلف استفاده کنید:

code
Production: /webhook/payment/verify
Staging:    /webhook/staging/payment/verify

رفع مشکلات

رفع مشکلات رایج

۱. Webhook درخواست دریافت نمی‌کند (404 Not Found)

علت: Workflow فعال نیست یا URL اشتباه است

راه‌حل

  • مطمئن شوید Workflow حتماً Active (فعال) است
  • از Production URL استفاده کنید نه Test URL
  • مسیر webhook را دقیق بررسی کنید (case-sensitive است)
  • بررسی کنید n8n در حال اجرا باشد
  • اگر پشت Reverse Proxy هستید، مسیر /webhook/ به درستی proxy شده باشد

۲. اشتباه بین Test URL و Production URL

علت: رایج‌ترین اشتباه کاربران n8n

راه‌حل

  • Test URL فقط وقتی دکمه "Listen for Test Event" فعال باشد کار می‌کند
  • Production URL فقط وقتی Workflow فعال (Active) باشد کار می‌کند
  • فرمت Test: https://n8n.example.com/webhook-test/path
  • فرمت Production: https://n8n.example.com/webhook/path
  • برای اتصال سرویس‌های واقعی همیشه از Production استفاده کنید

۳. مشکلات SSL/HTTPS

علت: گواهی SSL نامعتبر یا ناقص، یا استفاده از HTTP بجای HTTPS

راه‌حل

  • اکثر سرویس‌ها (GitHub, Stripe, ZarinPal) فقط HTTPS قبول می‌کنند
  • از Let's Encrypt یا Cloudflare SSL استفاده کنید
  • مطمئن شوید زنجیره گواهی کامل است (fullchain)
  • WEBHOOK_URL در تنظیمات n8n باید HTTPS باشد
  • تنظیم محیطی: N8N_PROTOCOL=https

۴. Timeout و عدم پاسخ به موقع

علت: Workflow طولانی است و سرویس فراخوان timeout می‌کند

راه‌حل

  • Response Mode را روی Immediately تنظیم کنید
  • ابتدا پاسخ 200 برگردانید، سپس پردازش سنگین انجام شود
  • برای پرداخت‌ها: فوراً تایید دریافت بفرستید
  • اکثر سرویس‌ها ۵ تا ۳۰ ثانیه timeout دارند
  • از Respond to Webhook Node در ابتدای workflow استفاده کنید

۵. خطا در دریافت Binary Data (فایل)

علت: تنظیمات باینری فعال نیست یا Content-Type اشتباه است

راه‌حل

  • گزینه Binary Data را در تنظیمات Webhook فعال کنید
  • Content-Type درخواست باید multipart/form-data باشد
  • نام فیلد فایل را در Binary Property Name مشخص کنید
  • حداکثر حجم فایل n8n را بررسی کنید: N8N_PAYLOAD_SIZE_MAX

۶. مشکلات CORS (Cross-Origin)

علت: مرورگر درخواست Cross-Origin را مسدود می‌کند

راه‌حل

  • در تنظیمات Webhook، Response Headers اضافه کنید:

Access-Control-Allow-Origin: * (یا دامنه خاص)

  • n8n خودکار به OPTIONS respond می‌کند
  • اگر مشکل ادامه دارد، CORS را در Reverse Proxy (nginx) تنظیم کنید
  • از Access-Control-Allow-Headers و Access-Control-Allow-Methods استفاده کنید

۷. خطای احراز هویت (401 Unauthorized)

علت: اطلاعات احراز هویت اشتباه یا ارسال نمی‌شود

راه‌حل

  • مطمئن شوید Header Auth دقیقاً با نام و مقدار تنظیم‌شده مطابقت دارد
  • برای Basic Auth: هدر Authorization: Basic base64(user:pass)
  • با Postman یا curl ابتدا تست کنید
  • توجه: نام Header در n8n حساس به حروف بزرگ/کوچک نیست

۸. خطای Payload Too Large (413)

علت: حجم داده ارسالی بیش از حد مجاز n8n

راه‌حل

  • محدودیت پیش‌فرض n8n: حدود 16MB
  • متغیر محیطی N8N_PAYLOAD_SIZE_MAX را افزایش دهید
  • اگر پشت nginx هستید: client_max_body_size 100m;
  • برای فایل‌های بزرگ: فایل را روی Object Storage آپلود کنید و فقط URL را ارسال کنید

۹. تکرار اجرای Webhook (Duplicate Triggers)

علت: سرویس فراخوان چندبار retry می‌کند

راه‌حل

  • اکثر سرویس‌ها (Stripe, GitHub) در صورت عدم دریافت 2xx، مجدداً تلاش می‌کنند
  • فوراً پاسخ 200 برگردانید (Response Mode: Immediately)
  • از Idempotency Key استفاده کنید:

ذخیره شناسه رویداد در دیتابیس و بررسی تکراری نبودن

  • برای ZarinPal: Authority را بررسی کنید که قبلاً پردازش نشده باشد

۱۰. n8n پشت Reverse Proxy کار نمی‌کند

علت: تنظیمات proxy webhook path را تغییر می‌دهد

راه‌حل

  • WEBHOOK_URL را با آدرس عمومی تنظیم کنید:

WEBHOOK_URL=https://n8n.yourdomain.com/

  • در nginx:

location /webhook/ { proxy_pass http://localhost:5678/webhook/; } location /webhook-test/ { proxy_pass http://localhost:5678/webhook-test/; }

  • هدرهای proxy: proxy_set_header Host $host;
  • proxy_set_header X-Forwarded-Proto $scheme;

۱۱. داده خالی دریافت می‌شود

علت: Content-Type اشتباه یا بدنه خالی ارسال می‌شود

راه‌حل

  • بررسی Content-Type: برای JSON باید application/json باشد
  • برای فرم: application/x-www-form-urlencoded یا multipart/form-data
  • داده‌ها در $json.body (POST) یا $json.query (GET) هستند
  • از Raw Body برای بررسی داده خام استفاده کنید
اشتراک‌گذاری:

آیا این مستندات مفید بود؟