OpenClaw Hooks: Build Event-Driven Automations That Scale

The teams running the most capable OpenClaw deployments aren't polling for agent output. They're reacting to it. When an agent completes a research task, a hook fires to Notion and creates a page. When an agent fails, a hook fires to PagerDuty and opens an incident. When a Telegram message arrives, a hook fires to a logging service for compliance. This is the architecture that scales — and it's three lines of YAML to set up.

What Hooks Are

An OpenClaw hook is an HTTP webhook registration in gateway.yaml. When a specified event occurs in the gateway, the gateway POSTs a JSON payload to your registered URL. Your endpoint receives the payload and can do anything with it — update a database, send a Slack message, trigger a CI pipeline, write to a spreadsheet.

The gateway delivers hooks asynchronously. This means hook delivery doesn't block message processing. If your endpoint is slow, the agent continues operating normally. The gateway doesn't wait for your endpoint to respond before moving on. This is the right design for integration — your monitoring and automation systems shouldn't slow down your agents.

Available Events

As of early 2025, OpenClaw supports nine hookable event types. Each serves a different automation need:

• message.received — A user message arrived on any channel. Fires before the agent processes it. Useful for logging, content filtering, or triggering pre-processing.
• message.sent — The agent sent a response. Fires after delivery. Useful for audit logging, CRM updates, or feeding responses to downstream systems.
• task.completed — A scheduled or cron task finished successfully. Fires with the task name and output summary.
• task.failed — A task failed or exceeded its timeout. Fires with the error type and last known state. Essential for alerting on automation failures.
• agent.online — An agent connected or reconnected to the gateway. Useful for incident resolution triggers.
• agent.offline — An agent disconnected or missed heartbeats. Fire this to PagerDuty or your on-call system.
• channel.connected — A messaging channel (Telegram, Slack, etc.) successfully connected.
• channel.disconnected — A channel dropped its connection. Fires with the channel type and disconnect reason.
• skill.invoked — A skill was called during agent processing. Useful for usage metering or debugging skill execution patterns.

Configuration

Add a hooks block to your gateway.yaml. You can register multiple hooks, each with its own URL and event filter:

hooks:
  - url: "https://hooks.slack.com/services/T00/B00/xxx"
    events:
      - agent.offline
      - task.failed
    headers:
      X-Openclaw-Secret: "your-secret-token-here"

  - url: "https://your-crm.com/webhooks/openclaw"
    events:
      - message.sent
    filter:
      channelId: "telegram-main"
    headers:
      Authorization: "Bearer crm-api-token"

  - url: "https://audit-log.internal/events"
    events:
      - message.received
      - message.sent
      - skill.invoked

The filter block is particularly useful. Without it, hooks fire for all channels and agents. A busy deployment with five channels would send every message.received event to every hook endpoint — that's potentially thousands of requests per hour to each URL. Filter by channelId, agentName, or skillName to scope delivery precisely.

Hook Payload Structure

Every hook payload shares a common envelope with event-specific fields. Here's the message.sent payload structure:

{
  "event": "message.sent",
  "timestamp": "2025-02-09T11:34:22Z",
  "gatewayId": "gw-prod-01",
  "agentName": "customer-support",
  "channelId": "telegram-main",
  "channelType": "telegram",
  "payload": {
    "messageId": "msg-8821",
    "text": "Your order ships tomorrow. Tracking: 1Z999...",
    "recipientId": "user-4492",
    "tokensUsed": 312,
    "modelUsed": "claude-sonnet-4-6"
  }
}

For task events, the payload includes taskName, duration, and output. For agent events, it includes consecutiveMisses and lastSeen. The complete payload schema for each event type is in the hooks documentation guide.

Securing Hook Endpoints

Anyone who knows your hook URL can POST to it and inject fake events into your automation pipeline. This is a real attack vector — fake task.completed events that trigger database writes, fake agent.offline events that open spurious incidents. Protect every endpoint.

The simplest approach: add a secret header in your hook config and verify it in your endpoint:

# In gateway.yaml
hooks:
  - url: "https://your-endpoint.com/webhook"
    events: [task.completed]
    headers:
      X-Openclaw-Secret: "sk-your-random-secret-here"

# In your endpoint (Python/Flask)
from flask import Flask, request, abort

SECRET = "sk-your-random-secret-here"

@app.route("/webhook", methods=["POST"])
def webhook():
    if request.headers.get("X-Openclaw-Secret") != SECRET:
        abort(401)
    data = request.json
    # Process event...
    return "", 200

For higher-security environments, implement HMAC signature verification. Generate a shared secret, use it to sign the payload in a header like X-Openclaw-Signature, and verify the signature in your endpoint. This prevents both unauthorized access and payload tampering.

Common Mistakes

Not filtering by event or channel is the most common mistake. A single hook registered for all events on a busy deployment generates thousands of requests per hour to your endpoint. Your endpoint's rate limits will throttle hook delivery, causing missed events. Always scope hooks to the specific events your automation actually needs.

Using a slow HTTP endpoint directly instead of a queue. If your endpoint takes 2 seconds to process (database write + external API call), and you get 100 message.sent events per minute, you have 200 seconds of processing per minute. The gateway doesn't back-pressure this — events queue internally until they can be delivered, but internal queue limits apply. A fast queue receiver that hands off to async workers is the correct pattern.

Forgetting to verify the secret header. Test this by posting a fake event to your endpoint without the secret header. If your automation pipeline processes it, you have an unprotected endpoint. Add verification before deploying to production.

Frequently Asked Questions

What are OpenClaw hooks?

OpenClaw hooks are HTTP webhooks that fire when specific gateway events occur. You register a URL in gateway.yaml with a list of event types, and the gateway POSTs a JSON payload to your URL on each matching event. This connects OpenClaw to any external system without polling or custom middleware.

What events can I hook into in OpenClaw?

Nine event types are available: message.received, message.sent, task.completed, task.failed, agent.online, agent.offline, channel.connected, channel.disconnected, and skill.invoked. Each has a distinct JSON payload structure. You can register multiple hooks and filter each one to specific channels or agents.

How do I configure a hook in OpenClaw?

Add a hooks block to gateway.yaml with a url, an events list, optional filter conditions, and optional headers for auth. The gateway delivers hooks asynchronously so they never block agent message processing. Restart the gateway after any hook configuration change.

Are OpenClaw hooks delivered reliably?

Hook delivery is fire-and-forget with no built-in retry. If your endpoint is down or returns an error, the event is logged as failed and not retried. For reliability, use a durable message queue as the hook URL — the queue receives events reliably and your processing code handles retries independently.

Can I filter hook payloads by channel or agent?

Yes. Each hook entry supports a filter block where you can restrict delivery to specific channelId, agentName, or skillName values. Events that don't match the filter are silently skipped. Always filter to avoid overwhelming your endpoint with events from channels you don't care about.

How do I secure hook endpoints?

Add a secret value in the hook's headers block and verify it in your endpoint before processing any payload. Without verification, anyone who discovers your URL can send fake events. For higher security, implement HMAC signature verification on the full payload body.