Plugin вебхуків

Plugin Webhooks додає автентифіковані HTTP-маршрути, щоб довірена зовнішня система (Zapier, n8n, завдання CI, внутрішній сервіс) могла створювати керовані TaskFlow OpenClaw і керувати ними через HTTP без написання власного плагіна.

Plugin працює всередині процесу Gateway. Для віддаленого 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",            },          },        },      },    },  },}

Поля маршруту:

secret приймає звичайний рядок або SecretRef: { source: "env" | "file" | "exec", provider: "default", id: "..." }.

Кожен налаштований маршрут реєструється під час запуску незалежно від того, чи вдається наразі отримати значення його секрету. Секрет, значення якого неможливо отримати, не вимикає маршрут і не призводить до його пропуску — запити до нього не проходять автентифікацію (401), доки значення секрету не стане доступним. Значення SecretRef отримуються повторно для кожного запиту, тому ротація базового секрету (змінної середовища, файлу або результату виконання команди) набуває чинності без перезапуску Gateway.

Модель безпеки

Кожен маршрут діє з повноваженнями TaskFlow налаштованого sessionKey: він може переглядати й змінювати будь-який TaskFlow, що належить цьому сеансу. Доступ до TaskFlow завжди здійснюється через api.runtime.tasks.managedFlows.bindSession(...), тому маршрут ніколи не може діяти поза межами прив'язаного сеансу. Щоб обмежити масштаб потенційної шкоди:

• Використовуйте надійний унікальний секрет для кожного маршруту.
• Віддавайте перевагу SecretRef, а не вбудованому секрету у відкритому тексті.
• Прив'язуйте маршрути до найвужчого сеансу, придатного для робочого процесу.
• Відкривайте доступ лише до потрібного шляху Webhook.

Порядок обробки запитів для кожного шляху: перевірка методу HTTP (лише POST) і Content-Type: application/json, потім обмеження частоти у фіксованому часовому вікні (120 запитів на 60-секундне вікно для кожної комбінації шляху й IP-адреси клієнта, до 4 096 відстежуваних ключів), потім обмеження одночасно оброблюваних запитів (8 паралельних запитів на ключ, до 4 096 відстежуваних ключів), потім автентифікація за спільним секретом, а потім читання тіла запиту у форматі JSON з обмеженнями 256 КБ і 15 секунд. Запити, що не проходять попередню перевірку, ніколи не доходять до наступних.

Формат запиту

Надсилайте запити 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"}'

Підтримувані дії

Дії, що вносять зміни (set_waiting, resume_flow, finish_flow, fail_flow, request_cancel), потребують flowId і expectedRevision для оптимістичного керування конкурентним доступом; застаріла ревізія повертає 409 revision_conflict.

create_flow

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

run_task

Дозволені значення runtime: subagent, acp. Поля startedAt, lastEventAt і progressSummary припустимі лише тоді, коли status має значення "running"; надсилання їх із будь-яким іншим станом повертає 400 invalid_request.

{  "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": {}}

Подання потоків і завдань ніколи не містять метаданих власника або сеансу, тому відповіді не можуть розкрити прив'язаний до маршруту sessionKey. Значення code включають not_found, not_managed, revision_conflict, persist_failed, cancel_requested, cancel_pending, terminal, invalid_request, request_rejected і резервні коди, специфічні для дій (mutation_rejected, create_rejected, task_not_created, cancel_rejected), коли внесення змін відхилено з причини, не охопленої зазначеними вище кодами.

Пов'язані матеріали

• Хуки — внутрішні хуки, керовані подіями, порівняно із цим мостом TaskFlow на основі HTTP
• Вебхуки Gateway (конфігурація hooks.*) — окрема універсальна функція HTTP-кінцевої точки Gateway; це не те саме, що маршрути цього плагіна
• SDK середовища виконання плагінів
• Вебхуки CLI