Using Webhooks in OpenClaw

Why webhooks matter

Webhooks are how OpenClaw stops being just a chat interface and starts acting like an operations layer. Instead of polling everything manually, external tools can push events into OpenClaw the moment something happens.

First, know the two different hook systems

OpenClaw uses the word hooks in two different ways, and that trips people up.

For external integrations, you want the HTTP webhook surface under the hooks config block.

Step 1: enable webhook ingress

Edit your OpenClaw config, usually ~/.openclaw/openclaw.json, and add a dedicated hooks section.

{
  "hooks": {
    "enabled": true,
    "token": "replace-with-a-long-random-secret",
    "path": "/hooks",
    "maxBodyBytes": 262144,
    "defaultSessionKey": "hook:ingress",
    "allowRequestSessionKey": false,
    "allowedSessionKeyPrefixes": ["hook:"],
    "allowedAgentIds": ["hooks", "main"],
    "presets": ["gmail"],
    "transformsDir": "~/.openclaw/hooks/transforms",
    "mappings": []
  }
}

Step 2: authenticate requests correctly

OpenClaw accepts the hook token in a header, not the query string.

Authorization: Bearer <token>
# or
x-openclaw-token: <token>

Step 3: choose the right endpoint

A) Use /hooks/wake for lightweight nudges

This is the smallest possible webhook pattern. It does not ask an isolated agent to solve a big task. It simply injects an event for the main session.

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

• text is required
• mode can be now or next-heartbeat
• Best for simple notifications, not full reasoning workflows

B) Use /hooks/agent for direct isolated runs

This is the endpoint to use when the incoming event should produce an actual agent turn.

curl -X POST http://127.0.0.1:18789/hooks/agent   -H 'Authorization: Bearer SECRET'   -H 'Content-Type: application/json'   -d '{
    "message": "Summarize this failed deployment and tell me the likely cause",
    "name": "Deploy Alert",
    "agentId": "hooks",
    "deliver": true,
    "channel": "last",
    "model": "openai/gpt-5.4-mini",
    "thinking": "medium",
    "timeoutSeconds": 90
  }'

Supported fields include message, name, agentId, sessionKey, wakeMode, deliver, channel, to, model, thinking, and timeoutSeconds.

C) Use mapped hooks for real integrations

Mapped hooks are usually the best long-term pattern. They let each sender keep its own payload format while OpenClaw transforms that payload into a clean wake or agent action.

{
  "hooks": {
    "enabled": true,
    "token": "replace-with-a-long-random-secret",
    "path": "/hooks",
    "defaultSessionKey": "hook:ingress",
    "allowedSessionKeyPrefixes": ["hook:"],
    "allowedAgentIds": ["hooks"],
    "mappings": [
      {
        "match": { "path": "github-pr" },
        "action": "agent",
        "agentId": "hooks",
        "wakeMode": "now",
        "name": "GitHub PR",
        "sessionKey": "hook:github:pr:{{pull_request.number}}",
        "messageTemplate": "Repository: {{repository.full_name}}
PR: #{{pull_request.number}} {{pull_request.title}}
Action: {{action}}
Author: {{pull_request.user.login}}",
        "deliver": true,
        "channel": "last",
        "model": "openai/gpt-5.4-mini"
      }
    ]
  }
}

That gives you an endpoint like POST /hooks/github-pr. OpenClaw reads the incoming payload, fills the template, and launches a clean agent run.

Step 4: leverage Gmail Pub/Sub without building it from scratch

OpenClaw already ships with Gmail webhook helpers. If your goal is inbox-triggered automation, use the helper instead of inventing your own bridge first.

openclaw webhooks gmail setup --account [email protected]
openclaw webhooks gmail run

Useful setup variations include:

openclaw webhooks gmail setup --account [email protected] --project my-gcp-project --json
openclaw webhooks gmail setup --account [email protected] --hook-url https://gateway.example.com/hooks/gmail

The helper supports flags like --topic, --subscription, --hook-token, --push-token, --include-body, --max-bytes, and Tailscale options for public ingress.

Step 5: use cron when OpenClaw needs to call out

Webhook workflows are often bidirectional. External systems call OpenClaw, then OpenClaw later needs to POST somewhere else. For scheduled outbound delivery, use cron's webhook delivery mode rather than hacking your own runner.

{
  "cron": {
    "enabled": true,
    "webhookToken": "replace-with-dedicated-outbound-token"
  }
}

OpenClaw cron jobs support delivery modes of announce, webhook, or none. That means you can combine inbound hooks, isolated agent reasoning, and outbound webhooks into one clean automation chain.

Production patterns that actually hold up

Recent OpenClaw changes worth knowing

If you read an older webhook tutorial, this is the part that may be missing.

• The core endpoints did not change, but validation got stricter. Recent docs and security checks now explicitly reject token reuse with Gateway auth, reject hooks.path: "/", and warn when request-driven session overrides are too open.
• Webhook docs moved. The dedicated webhook docs page now points to the Scheduled Tasks documentation section, so newer webhook guidance lives under the broader automation docs.
• Recent releases hardened the edges around hooks. OpenClaw's April and May 2026 updates mention webhook-driven TaskFlow ingress, untrusted wake-hook owner downgrades, tighter hook CLI authority, stricter webhook parsing, webhook-auth throttling, and rate-limiting fixes on some channel webhook integrations.
• Some hook-related fields are intentionally not SecretRef targets. In current docs, hooks.token, hooks.gmail.pushToken, and hooks.mappings[].sessionKey are called out as unsupported SecretRef surfaces.

Troubleshooting

Best practices

• Use mapped hooks for long-lived integrations instead of stuffing raw JSON into /hooks/agent
• Keep session keys predictable and prefix-scoped
• Use a separate hooks agent when you want cleaner operational boundaries
• Pair inbound webhooks with cron jobs and custom skills for full workflows
• Run a security audit after changes, especially if you opened ingress to the public internet