Clarification on webhooks-setup

[jolly remnant]

@keen sinew I am planning to integrate webhooks on my agent and I need a bit of clarification here...

Docs say I need to extend the openclaw.conf file on one part while another part mentions a webhooks plugin and google search reveal that you need something like a webhook proxy. I am confused as all I want to do is to use various services to fire events at my agent (changedetection.io, node-red,...)

[sonic meadow]

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

[keen sinew]

You’re seeing three related but different things:

1. hooks config = the built-in Gateway webhook ingress. This is probably what you want for changedetection.io / Node-RED firing events at an agent.
2. webhooks plugin = a separate plugin for authenticated TaskFlow control from trusted external automation. Use this if the external system needs to create/resume/run managed TaskFlows, not just “tell my agent something happened.”
3. Webhook proxy/tunnel = only needed if the sender cannot reach your Gateway directly. If Node-RED/changedetection is on the same host/LAN/tailnet, point it straight at the Gateway. If it’s a cloud service, you need HTTPS exposure via Tailscale Funnel/Serve, ngrok, a reverse proxy, etc.

For your use case I’d start with built-in hooks:

{
  hooks: {
    enabled: true,
    token: "use-a-dedicated-strong-secret",
    path: "/hooks",
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,

[keen sinew]

    allowedAgentIds: ["main"],
    mappings: [
      {
        match: { path: "changedetection" },
        action: "agent",
        agentId: "main",
        name: "changedetection.io",
        messageTemplate: "changedetection.io event:
{{body}}",
        deliver: true
      }
    ]
  }
}

[keen sinew]

Then POST to:

curl -X POST http://127.0.0.1:18789/hooks/changedetection \
  -H 'Authorization: Bearer use-a-dedicated-strong-secret' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com","change":"price changed"}'

There are also generic endpoints:

• POST /hooks/wake queues a system event for the main session.
• POST /hooks/agent runs an isolated agent turn.
• POST /hooks/<name> uses your hooks.mappings.

Important bits: don’t reuse your Gateway auth token as hooks.token; auth is header-only (Authorization: Bearer ... or x-openclaw-token); keep hooks.path as something like /hooks, not /.

Docs:

[keen sinew]

https://docs.openclaw.ai/automation/cron-jobs#webhooks
https://docs.openclaw.ai/gateway/configuration-reference#hooks
https://docs.openclaw.ai/plugins/webhooks

Also, please run openclaw --version when you wire this up. The hooks/webhooks docs moved around recently, so version mismatches are a common source of confusion.

[jolly remnant]

I am running OpenClaw 2026.5.22 (a374c3a) - updated today. Is there a way to do openclaw config commands instead of working on the json? Don't feel too comfy with messing up my json files.

[keen sinew]

Yep. Use openclaw config set; that’s safer than hand-editing JSON, and you can dry-run + validate before committing.

For the built-in hooks setup, I’d do it in one batch first as a dry run:

openclaw config set --batch-json '[
  { "path": "hooks.enabled", "value": true },
  { "path": "hooks.token", "value": "replace-with-a-long-random-secret" },
  { "path": "hooks.path", "value": "/hooks" },
  { "path": "hooks.defaultSessionKey", "value": "hook:ingress" },
  { "path": "hooks.allowRequestSessionKey", "value": false },
  { "path": "hooks.allowedAgentIds", "value": ["main"] },
  {
    "path": "hooks.mappings",
    "value": [
      {

[keen sinew]

        "match": { "path": "changedetection" },
        "action": "agent",
        "agentId": "main",
        "name": "changedetection.io",
        "messageTemplate": "Webhook payload:
{{payload}}",
        "deliver": true
      }
    ]
  }
]' --dry-run

openclaw config validate

If the dry run looks good, run the same openclaw config set --batch-json '...' command again without --dry-run, then:

[keen sinew]

openclaw config validate
openclaw gateway restart

You can inspect what got written with:

openclaw config get hooks

Then changedetection.io / Node-RED would POST to:

curl -X POST http://127.0.0.1:18789/hooks/changedetection \
  -H 'Authorization: Bearer replace-with-a-long-random-secret' \

[keen sinew]

  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com","event":"changed"}'

Docs for the command syntax: https://docs.openclaw.ai/cli/config
Hooks reference: https://docs.openclaw.ai/gateway/configuration-reference#hooks

[jolly remnant]

your config-set errors out: Error: Failed to parse --batch-json: SyntaxError: JSON5: invalid character '\n' at 16:0

[keen sinew]

Yep, that one’s on me — --batch-json is fussy when copied through Discord/shells. Use separate config set calls instead; easier to audit and no multiline JSON blob:

openclaw config set hooks.enabled true --strict-json
openclaw config set hooks.token "replace-with-a-long-random-secret"
openclaw config set hooks.path "/hooks"
openclaw config set hooks.defaultSessionKey "hook:ingress"
openclaw config set hooks.allowRequestSessionKey false --strict-json
openclaw config set hooks.allowedAgentIds '["main"]' --strict-json
openclaw config set hooks.mappings '[{"match":{"path":"changedetection"},"action":"agent","agentId":"main","name":"changedetection.io","messageTemplate":"Webhook payload:
{{payload}}","deliver":true}]' --strict-json
openclaw config validate
openclaw gateway restart

If you want to test first, add --dry-run to each config set command.

[keen sinew]

Alternative if you still want batch mode: put the JSON array in a file and use openclaw config set --batch-file ./hooks.batch.json --dry-run. The inline --batch-json form is fine for compact one-liners, but it’s annoying for longer nested config.

Docs: https://docs.openclaw.ai/cli/config

[jolly remnant]

so we have one changedetection endpoint on /hooks/changedetection.io where that app will post to. Gotcha.

How does the agent know what to do with that info pushed to there?

[keen sinew]

The agent only knows because the hook mapping turns the incoming POST body into an agent message.

In the example, this part is the “instruction”:

messageTemplate: "Webhook payload:
{{payload}}"

So when changedetection.io posts JSON to /hooks/changedetection.io, OpenClaw renders that template, starts an isolated agent turn, and gives the agent that rendered message. The agent then follows:

• its normal system/workspace instructions
• the selected agentId config, if you route to one
• the text you put in messageTemplate
• the webhook payload fields you include with {{...}}

For anything beyond “here is a payload”, make the template explicit. Example:

[keen sinew]

openclaw config set hooks.mappings '[{
  "match": { "path": "changedetection.io" },
  "action": "agent",
  "agentId": "main",
  "name": "changedetection.io",
  "messageTemplate": "A changedetection.io webhook fired. Inspect the payload, decide whether it needs attention, and send me a concise summary only if the change looks important. Payload:
{{payload}}",
  "deliver": true
}]' --strict-json

If different endpoints should behave differently, make separate mappings:

• /hooks/changedetection.io → summarize website changes
• /hooks/node-red → handle automation events
• /hooks/alerts → urgent notification policy

[keen sinew]

For more structured payloads, reference fields directly, e.g. {{payload.url}}, {{payload.title}}, {{payload.diff}}. If changedetection.io sends a form/body shape that doesn’t map cleanly, use a small transform later, but I’d start with the template first.