Automating OpenClaw with Webhooks and Hooks

OpenClaw isn't just a chat gateway — it's an event-driven platform. Two of its most powerful automation features are hooks (internal event handlers) and webhooks (external HTTP triggers). Together, they let you wire OpenClaw into practically anything: CI pipelines, email notifications, CRM events, or your own custom workflows.

Let's break down both systems and show you how to use them.

Hooks: React to What Happens Inside

Hooks are small scripts that run automatically when something happens inside the Gateway. Think of them as event listeners for your agent's lifecycle.

What Can Trigger a Hook?

/new — a session resets
/reset — session context cleared
/stop — agent stops
Gateway boot events
Agent bootstrap events

Built-in Hooks

OpenClaw ships with four hooks out of the box:

💾 session-memory — saves session context to memory/ when you issue /new
📎 bootstrap-extra-files — injects additional workspace files during agent bootstrap
📝 command-logger — logs all commands to ~/.openclaw/logs/commands.log
🚀 boot-md — runs BOOT.md when the gateway starts

Managing Hooks

# List all available hooks
openclaw hooks list

# Enable a specific hook
openclaw hooks enable session-memory

# Check which hooks are active
openclaw hooks check

# Get details about a hook
openclaw hooks info session-memory

Writing Your Own Hook

A hook is just a directory with two files:

my-hook/
├── HOOK.md      # Metadata (YAML frontmatter)
└── handler.ts   # The actual logic

Here's a minimal handler that fires when you start a new session:

import type { HookHandler } from "../../src/hooks/hooks.js";

const handler: HookHandler = async (event) => {
  if (event.type !== "command" || event.action !== "new") return;

  console.log(`[my-hook] New session started: ${event.sessionKey}`);
  event.messages.push("🎉 Fresh session, fresh start!");
};

export default handler;

The HOOK.md frontmatter tells OpenClaw when to run it:

---
name: my-hook
description: "Fires on new sessions"
metadata:
  { "openclaw": { "emoji": "🎉", "events": ["command:new"] } }
---

Drop this in ~/.openclaw/hooks/my-hook/ or your workspace's hooks/ directory, enable it, and you're live.

Hook Discovery Order

Hooks are discovered from three locations (highest precedence first):

Workspace hooks — <workspace>/hooks/
Managed hooks — ~/.openclaw/hooks/
Bundled hooks — shipped with OpenClaw

This means you can override bundled behavior with your own version in your workspace.

Webhooks: Let the Outside World Talk to Your Agent

While hooks react to internal events, webhooks let external systems trigger your agent via HTTP. This is where things get really interesting.

Enabling Webhooks

Add this to your OpenClaw config:

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

Every request must authenticate via header:

Authorization: Bearer your-shared-secret

The Two Core Endpoints

`POST /hooks/wake` — Nudge Your Agent

Send a system event to the main session. Great for "hey, something happened" notifications.

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"}'

The agent sees this as a system event and can decide what to do — check the inbox, summarize the email, or ignore it if it's spam.

`POST /hooks/agent` — Run an Isolated Task

This is the heavy hitter. It spins up an isolated agent session, runs a task, and optionally delivers the result to a messaging channel.

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "Summarize the last 5 GitHub issues",
    "name": "GitHub",
    "deliver": true,
    "channel": "slack"
  }'

Key options:

message — what you want the agent to do
name — human-readable label (shows in session summaries)
agentId — route to a specific agent
deliver — send the result to a chat channel
channel — which channel (slack, telegram, whatsapp, discord, etc.)
model — override the model for this run
timeoutSeconds — max duration

Custom Mapped Hooks

You can also define named hooks via hooks.mappings in your config. These let you create custom endpoints like /hooks/github or /hooks/stripe that transform incoming payloads before passing them to your agent.

For complex transforms, you can write JS/TS modules in ~/.openclaw/hooks/transforms/ and reference them in your mapping config.

Real-World Use Cases

1. Email Triage

Set up Gmail Pub/Sub to hit /hooks/wake when new mail arrives. Your agent checks the inbox, categorizes messages, and flags anything urgent.

2. CI/CD Notifications

Wire your GitHub Actions workflow to call /hooks/agent on build failure. The agent analyzes the error, checks recent commits, and posts a summary to your Discord channel.

3. Session Journaling

Enable the session-memory hook so every /new command automatically saves your conversation context to disk. Your agent picks up where it left off next session.

4. CRM Event Processing

When a deal closes in your CRM, hit /hooks/agent with the deal details. The agent updates your project tracker, sends a congratulations message, and creates follow-up tasks.

5. Scheduled Report Delivery

Combine a cron job with a webhook call to generate daily/weekly reports. The cron fires, hits the webhook, the agent compiles data, and delivers a formatted summary to Telegram.

Security Notes

A few things to keep in mind:

Always use header-based auth. Query string tokens are rejected (returns 400).
Rate limiting is automatic. Repeated auth failures from the same IP trigger 429 responses with Retry-After headers.
Session key overrides are off by default. If you need them, explicitly enable allowRequestSessionKey and restrict prefixes.
Restrict agent routing with allowedAgentIds if you don't want external callers choosing which agent handles the request.

Recommended secure config:

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

Hooks + Webhooks = Full Automation

The real power is combining both systems. Webhooks bring external events in; hooks react to internal ones. Together, they turn OpenClaw from a chat tool into an automation engine.

Your agent isn't just waiting for you to type — it's listening to the world.

Start small. Enable session-memory. Set up one webhook from a service you already use. Watch what happens when your agent starts reacting to events instead of just responding to messages.

That's when it gets fun.