Webhooks¶

La Gateway (passerelle) peut exposer un petit point de terminaison HTTP de webhook pour des déclencheurs externes.

Activation¶

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
  },
}

Remarques :

• hooks.token est requis lorsque hooks.enabled=true.
• hooks.path est défini par défaut sur /hooks.

Authentification¶

Chaque requête doit inclure le jeton du hook. Préférez les en-têtes :

• Authorization: Bearer <token> (recommandé)
• x-openclaw-token: <token>
• Query-string tokens are rejected (?token=... returns 400).

Points de terminaison¶

POST /hooks/wake¶

Charge utile :

{ "text": "System line", "mode": "now" }

• text obligatoire (string) : La description de l’événement (p. ex., « New email received »).
• mode optionnel (now | next-heartbeat) : Indique s’il faut déclencher un heartbeat immédiat (par défaut now) ou attendre la prochaine vérification périodique.

Effet :

• Met en file d’attente un événement système pour la session principale
• Si mode=now, déclenche un heartbeat immédiat

POST /hooks/agent¶

Charge utile :

{
  "message": "Run this",
  "name": "Email",
  "sessionKey": "hook:email:msg-123",
  "wakeMode": "now",
  "deliver": true,
  "channel": "last",
  "to": "+15551234567",
  "model": "openai/gpt-5.2-mini",
  "thinking": "low",
  "timeoutSeconds": 120
}

• message obligatoire (string) : L’invite ou le message que l’agent doit traiter.
• name optionnel (string) : Nom lisible par un humain pour le hook (p. ex., « GitHub »), utilisé comme préfixe dans les résumés de session.
• agentId optional (string): Route this hook to a specific agent. Unknown IDs fall back to the default agent. When set, the hook runs using the resolved agent's workspace and configuration.
• sessionKey optionnel (string) : La clé utilisée pour identifier la session de l’agent. By default this field is rejected unless hooks.allowRequestSessionKey=true.
• wakeMode optionnel (now | next-heartbeat) : Indique s’il faut déclencher un heartbeat immédiat (par défaut now) ou attendre la prochaine vérification périodique.
• deliver optionnel (boolean) : Si true, la réponse de l’agent sera envoyée vers le canal de messagerie. Par défaut true. Les réponses qui ne sont que des accusés de réception de heartbeat sont automatiquement ignorées.
• channel optionnel (string) : Le canal de messagerie pour la livraison. L’un de : last, whatsapp, telegram, discord, slack, mattermost (plugin), signal, imessage, msteams. Par défaut last.
• to optionnel (string) : L’identifiant du destinataire pour le canal (p. ex., numéro de téléphone pour WhatsApp/Signal, identifiant de chat pour Telegram, identifiant de canal pour Discord/Slack/Mattermost (plugin), identifiant de conversation pour MS Teams). Par défaut, le dernier destinataire de la session principale.
• model optionnel (string) : Remplacement du modèle (p. ex., anthropic/claude-3-5-sonnet ou un alias). Doit figurer dans la liste des modèles autorisés si elle est restreinte.
• thinking optionnel (string) : Remplacement du niveau de réflexion (p. ex., low, medium, high).
• timeoutSeconds optionnel (number) : Durée maximale de l’exécution de l’agent en secondes.

Effet :

• Exécute un tour d’agent isolé (clé de session propre)
• Publie toujours un résumé dans la session principale
• Si wakeMode=now, déclenche un heartbeat immédiat

Session key policy (breaking change)¶

/hooks/agent payload sessionKey overrides are disabled by default.

• Recommended: set a fixed hooks.defaultSessionKey and keep request overrides off.
• Optional: allow request overrides only when needed, and restrict prefixes.

Recommended config:

{
  hooks: {
    enabled: true,
    token: "${OPENCLAW_HOOKS_TOKEN}",
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
  },
}

Compatibility config (legacy behavior):

{
  hooks: {
    enabled: true,
    token: "${OPENCLAW_HOOKS_TOKEN}",
    allowRequestSessionKey: true,
    allowedSessionKeyPrefixes: ["hook:"], // strongly recommended
  },
}

POST /hooks/<name> (mappé)¶

Les noms de hooks personnalisés sont résolus via hooks.mappings (voir la configuration). Un mappage peut transformer des charges utiles arbitraires en actions wake ou agent, avec des modèles optionnels ou des transformations de code.

Options de mappage (résumé) :

• hooks.presets: ["gmail"] active le mappage Gmail intégré.
• hooks.mappings vous permet de définir match, action et des modèles dans la configuration.
• hooks.transformsDir + transform.module charge un module JS/TS pour une logique personnalisée.
• hooks.transformsDir (if set) must stay within the transforms root under your OpenClaw config directory (typically ~/.openclaw/hooks/transforms).
• transform.module must resolve within the effective transforms directory (traversal/escape paths are rejected).
• Utilisez match.source pour conserver un point d’ingestion générique (routage piloté par la charge utile).
• Les transformations TS nécessitent un chargeur TS (p. ex., bun ou tsx) ou des .js précompilés à l’exécution.
• Définissez deliver: true + channel/to sur les mappages pour acheminer les réponses vers une surface de discussion (channel est défini par défaut sur last et retombe sur WhatsApp).
• agentId routes the hook to a specific agent; unknown IDs fall back to the default agent.
• hooks.allowedAgentIds restricts explicit agentId routing. Omit it (or include *) to allow any agent. Set [] to deny explicit agentId routing.
• hooks.defaultSessionKey sets the default session for hook agent runs when no explicit key is provided.
• hooks.allowRequestSessionKey controls whether /hooks/agent payloads may set sessionKey (default: false).
• hooks.allowedSessionKeyPrefixes optionally restricts explicit sessionKey values from request payloads and mappings.
• allowUnsafeExternalContent: true désactive l’enveloppe de sécurité du contenu externe pour ce hook (dangereux ; uniquement pour des sources internes de confiance).
• openclaw webhooks gmail setup écrit la configuration hooks.gmail pour openclaw webhooks gmail run. Voir Gmail Pub/Sub pour le flux complet de surveillance Gmail.

Réponses¶

• 200 pour /hooks/wake
• 202 pour /hooks/agent (exécution asynchrone démarrée)
• 401 en cas d’échec d’authentification
• 429 after repeated auth failures from the same client (check Retry-After)
• 400 en cas de charge utile invalide
• 413 pour les charges utiles trop volumineuses

Exemples¶

curl -X POST http://127.0.0.1:18789/hooks/wake \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"text":"New email received","mode":"now"}'

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'x-openclaw-token: SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Summarize inbox","name":"Email","wakeMode":"next-heartbeat"}'

Utiliser un modèle différent¶

Ajoutez model à la charge utile de l’agent (ou au mappage) pour remplacer le modèle pour cette exécution :

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'x-openclaw-token: SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.2-mini"}'

Si vous appliquez agents.defaults.models, assurez‑vous que le modèle de remplacement y est inclus.

curl -X POST http://127.0.0.1:18789/hooks/gmail \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"source":"gmail","messages":[{"from":"Ada","subject":"Hello","snippet":"Hi"}]}'

Sécurité¶

• Conservez les points de terminaison des hooks derrière loopback, un tailnet ou un proxy inverse de confiance.
• Utilisez un jeton de hook dédié ; ne réutilisez pas les jetons d’authentification de la Gateway (passerelle).
• Repeated auth failures are rate-limited per client address to slow brute-force attempts.
• If you use multi-agent routing, set hooks.allowedAgentIds to limit explicit agentId selection.
• Keep hooks.allowRequestSessionKey=false unless you require caller-selected sessions.
• If you enable request sessionKey, restrict hooks.allowedSessionKeyPrefixes (for example, ["hook:"]).
• Évitez d’inclure des charges utiles brutes sensibles dans les journaux des webhooks.
• Les charges utiles des hooks sont traitées comme non fiables et enveloppées par des limites de sécurité par défaut. Si vous devez désactiver cela pour un hook spécifique, définissez allowUnsafeExternalContent: true dans le mappage de ce hook (dangereux).