Skip to main content
El plugin Webhooks añade rutas HTTP autenticadas para que un sistema externo de confianza (Zapier, n8n, un trabajo de CI, un servicio interno) pueda crear y controlar TaskFlows administrados de OpenClaw mediante HTTP, sin escribir un plugin personalizado. El plugin se ejecuta dentro del proceso del Gateway. Para un Gateway remoto, instálelo y configúrelo en ese host y, después, reinicie el Gateway. Se distribuye sin rutas configuradas, por lo que no hace nada hasta que se añade al menos una ruta.

​
Configurar rutas

Establezca la configuración en plugins.entries.webhooks.config:
Campos de ruta: secret acepta una cadena de texto sin formato o una SecretRef: { source: "env" | "file" | "exec", provider: "default", id: "..." }. Las SecretRefs se resuelven en la instantánea de configuración de inicio del Gateway. Cuando el secreto de una ruta no se puede resolver, el Gateway continúa ejecutándose y esa ruta específica permanece registrada pero inactiva: las solicitudes reciben un error genérico de autenticación (401). Las demás rutas permanecen disponibles. Corrija el origen de la SecretRef y, después, recargue o reinicie el Gateway para activar la nueva instantánea. Los valores de SecretRef nunca se resuelven en la ruta pública de solicitudes.

​
Modelo de seguridad

Cada ruta actúa con la autoridad de TaskFlow de su sessionKey configurada: puede inspeccionar y modificar cualquier TaskFlow que pertenezca a esa sesión. El acceso a TaskFlow siempre pasa por api.runtime.tasks.managedFlows.bindSession(...), por lo que una ruta nunca puede actuar fuera de su sesión vinculada. Para limitar el alcance de los daños:
  • Utilice un secreto seguro y único para cada ruta.
  • Prefiera una SecretRef a un secreto de texto sin formato insertado directamente.
  • Vincule las rutas a la sesión más restringida que sea adecuada para el flujo de trabajo.
  • Exponga únicamente la ruta de Webhook específica que necesite.
Orden de procesamiento de solicitudes para cada ruta: comprobaciones del método HTTP (solo POST) y de Content-Type: application/json; después, limitación de frecuencia con ventana fija (120 solicitudes por cada ventana de 60 segundos por clave de ruta+IP del cliente, con hasta 4,096 claves registradas); después, limitación de solicitudes en curso (8 solicitudes simultáneas por clave, con hasta 4,096 claves registradas); después, autenticación mediante secreto compartido; y, por último, lectura de un cuerpo JSON de 256 KB / 15 segundos. Las solicitudes que no superan una comprobación anterior nunca llegan a las posteriores.

​
Formato de solicitud

Envíe solicitudes POST con Content-Type: application/json y Authorization: Bearer <secret> o x-openclaw-webhook-secret: <secret>:

​
Acciones compatibles

Las acciones de modificación (set_waiting, resume_flow, finish_flow, fail_flow, request_cancel) requieren flowId y expectedRevision para la concurrencia optimista; una revisión obsoleta devuelve 409 revision_conflict.

​
create_flow

​
run_task

Valores permitidos de runtime: subagent, acp. startedAt, lastEventAt y progressSummary solo son válidos cuando status es "running"; enviarlos con cualquier otro estado devuelve 400 invalid_request.

​
Estructura de la respuesta

Las vistas de flujos y tareas nunca incluyen metadatos del propietario o de la sesión, por lo que las respuestas no pueden filtrar la sessionKey vinculada a la ruta. Los valores de code incluyen not_found, not_managed, revision_conflict, persist_failed, cancel_requested, cancel_pending, terminal, invalid_request, request_rejected y códigos de reserva específicos de cada acción (mutation_rejected, create_rejected, task_not_created, cancel_rejected) cuando una modificación se rechaza por un motivo que no cubren los códigos con nombre anteriores.

​
Contenido relacionado