Плагин вебхуков

Плагин Webhooks добавляет аутентифицированные HTTP-маршруты, позволяющие доверенной внешней системе (Zapier, n8n, заданию CI, внутреннему сервису) создавать управляемые TaskFlow OpenClaw и управлять ими по HTTP без написания собственного плагина.

Плагин выполняется внутри процесса 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 KB с тайм-аутом 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), когда изменение отклонено по причине, не охваченной указанными выше кодами.

Связанные материалы

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