Plugin Webhookها

Plugin Webhooks مسیرهای HTTP احراز هویت‌شده‌ای اضافه می‌کند که اتوماسیون خارجی را به TaskFlowهای OpenClaw متصل می‌کنند.

از آن زمانی استفاده کنید که می‌خواهید یک سامانه قابل اعتماد مانند Zapier، n8n، یک کار CI، یا یک سرویس داخلی، بدون نوشتن یک Plugin سفارشی در ابتدا، TaskFlowهای مدیریت‌شده را ایجاد و هدایت کند.

# محل اجرا

Plugin Webhooks داخل فرایند Gateway اجرا می‌شود.

اگر Gateway شما روی ماشین دیگری اجرا می‌شود، Plugin را روی همان میزبان Gateway نصب و پیکربندی کنید، سپس Gateway را بازراه‌اندازی کنید.

# پیکربندی مسیرها

پیکربندی را زیر plugins.entries.webhooks.config تنظیم کنید:

{
  plugins: {
    entries: {
      webhooks: {
        enabled: true,
        config: {
          routes: {
            zapier: {
              path: "/plugins/webhooks/zapier",
              sessionKey: "agent:main:main",
              secret: {
                source: "env",
                provider: "default",
                id: "OPENCLAW_WEBHOOK_SECRET",
              },
              controllerId: "webhooks/zapier",
              description: "Zapier TaskFlow bridge",
            },
          },
        },
      },
    },
  },
}

فیلدهای مسیر:

• enabled: اختیاری، پیش‌فرض true است
• path: اختیاری، پیش‌فرض /plugins/webhooks/<routeId> است
• sessionKey: نشست الزامی که مالک TaskFlowهای متصل‌شده است
• secret: secret مشترک یا SecretRef الزامی
• controllerId: شناسه کنترلر اختیاری برای جریان‌های مدیریت‌شده ایجادشده
• description: یادداشت اختیاری برای اپراتور

ورودی‌های پشتیبانی‌شده secret:

• رشته ساده
• SecretRef با source: "env" | "file" | "exec"

اگر یک مسیر متکی به secret نتواند secret خود را هنگام راه‌اندازی resolve کند، Plugin آن مسیر را نادیده می‌گیرد و به‌جای نمایان کردن یک endpoint خراب، هشدار ثبت می‌کند.

# مدل امنیتی

هر مسیر مورد اعتماد است تا با اختیار TaskFlow مربوط به sessionKey پیکربندی‌شده‌اش عمل کند.

یعنی مسیر می‌تواند TaskFlowهای متعلق به آن نشست را بررسی و تغییر دهد، بنابراین باید:

• برای هر مسیر از یک secret قوی و یکتا استفاده کنید
• ارجاع‌های secret را به secretهای متن ساده درون‌خطی ترجیح دهید
• مسیرها را به محدودترین نشستی متصل کنید که برای گردش کار مناسب است
• فقط همان مسیر Webhook مشخصی را که نیاز دارید در معرض دسترس قرار دهید

Plugin اعمال می‌کند:

• احراز هویت با secret مشترک
• محافظ‌های اندازه بدنه درخواست و زمان‌پایان
• محدودسازی نرخ با پنجره ثابت
• محدودسازی درخواست‌های در حال اجرا
• دسترسی TaskFlow مقید به مالک از طریق api.runtime.tasks.managedFlows.bindSession(...)

# قالب درخواست

درخواست‌های POST را با این موارد ارسال کنید:

• Content-Type: application/json
• Authorization: Bearer <secret> یا x-openclaw-webhook-secret: <secret>

نمونه:

curl -X POST https://gateway.example.com/plugins/webhooks/zapier \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_SHARED_SECRET' \
  -d '{"action":"create_flow","goal":"Review inbound queue"}'

# کنش‌های پشتیبانی‌شده

Plugin در حال حاضر این مقادیر JSON action را می‌پذیرد:

• create_flow
• get_flow
• list_flows
• find_latest_flow
• resolve_flow
• get_task_summary
• set_waiting
• resume_flow
• finish_flow
• fail_flow
• request_cancel
• cancel_flow
• run_task

# create_flow

یک TaskFlow مدیریت‌شده برای نشست متصل به مسیر ایجاد می‌کند.

نمونه:

{
  "action": "create_flow",
  "goal": "Review inbound queue",
  "status": "queued",
  "notifyPolicy": "done_only"
}

# run_task

یک کار فرزند مدیریت‌شده داخل یک TaskFlow مدیریت‌شده موجود ایجاد می‌کند.

زمان‌های اجرای مجاز عبارت‌اند از:

• subagent
• acp

نمونه:

{
  "action": "run_task",
  "flowId": "flow_123",
  "runtime": "acp",
  "childSessionKey": "agent:main:acp:worker",
  "task": "Inspect the next message batch"
}

# شکل پاسخ

پاسخ‌های موفق این را برمی‌گردانند:

{
  "ok": true,
  "routeId": "zapier",
  "result": {}
}

درخواست‌های ردشده این را برمی‌گردانند:

{
  "ok": false,
  "routeId": "zapier",
  "code": "not_found",
  "error": "TaskFlow not found.",
  "result": {}
}

Plugin عمداً فراداده مالک/نشست را از پاسخ‌های Webhook پاک می‌کند.

# مستندات مرتبط

• SDK زمان اجرای Plugin
• نمای کلی Hookها و Webhookها
• Webhookهای CLI