OpenClaw Webhook Integration and Event Callbacks

Introduction

In real-world production environments, AI Agents rarely operate in isolation — they need bidirectional integration with existing enterprise systems. OpenClaw provides a comprehensive Webhook mechanism that allows you to send callback notifications to external systems when specific events occur, and also supports receiving events from external systems to trigger Agent actions.

This article provides a thorough overview of OpenClaw's Webhook integration options to help you build event-driven AI workflows.

Webhook Fundamentals

OpenClaw's Webhook system operates in two directions:

• Outgoing Webhooks: When a specific event occurs within OpenClaw, an HTTP POST request is sent to a URL you configure
• Incoming Webhooks: External systems trigger OpenClaw Agent tasks via HTTP requests

Outgoing flow:
  OpenClaw Event -> HTTP POST -> Your Server

Incoming flow:
  Your Server -> HTTP POST -> OpenClaw -> Agent Processing -> Callback Notification

Configuring Outgoing Webhooks

Basic Configuration

Add Webhook configuration in openclaw.json5:

{
  webhooks: {
    endpoints: [
      {
        // Webhook name
        name: "main-webhook",
        // Target URL
        url: "https://your-server.com/openclaw/events",
        // Signing secret (for verifying request authenticity)
        secret: "whsec_xxxxxxxxxxxxxxxx",
        // Subscribed event types
        events: [
          "message.received",
          "message.sent",
          "session.created",
          "session.ended",
          "tool.called",
          "tool.completed",
          "error.occurred"
        ],
        // Retry configuration
        retry: {
          maxAttempts: 3,
          backoffMs: 1000
        }
      }
    ]
  }
}

Event Types Explained

Event Payload Format

Each Webhook request body follows a unified format:

{
  "id": "evt_abc123def456",
  "type": "message.sent",
  "timestamp": "2026-03-14T10:30:00Z",
  "instanceId": "node-1",
  "data": {
    "agentId": "my-agent",
    "sessionId": "session-001",
    "channel": "telegram",
    "userId": "user_12345",
    "message": {
      "role": "assistant",
      "content": "This is the AI's reply...",
      "messageId": "msg_xyz789"
    },
    "model": "claude-sonnet-4-20250514",
    "usage": {
      "inputTokens": 200,
      "outputTokens": 450
    }
  }
}

Signature Verification

To ensure that Webhook requests genuinely come from your OpenClaw instance, each request carries signature headers:

X-OpenClaw-Signature: sha256=5a8c3f2b...
X-OpenClaw-Timestamp: 1710400200

Verification example (Node.js):

const crypto = require("crypto");

function verifyWebhook(payload, signature, timestamp, secret) {
  const signedPayload = `${timestamp}.${payload}`;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(signedPayload)
    .digest("hex");
  return `sha256=${expected}` === signature;
}

Configuring Incoming Webhooks

Incoming Webhooks allow external systems to proactively trigger OpenClaw Agents:

{
  webhooks: {
    inbound: {
      enabled: true,
      // Inbound Webhook path prefix
      basePath: "/webhooks/inbound",
      // Endpoint configuration
      endpoints: {
        // Triggered when receiving POST /webhooks/inbound/alert
        "alert": {
          agentId: "alert-handler",
          // Message template with variable substitution
          template: "Alert received: {{body.title}} - Severity: {{body.severity}}"
        },
        "deploy": {
          agentId: "devops-agent",
          template: "{{body.repo}}'s {{body.branch}} branch deployment {{body.status}}"
        }
      }
    }
  }
}

External system call example:

# CI/CD deployment notification
curl -X POST http://openclaw.example.com/webhooks/inbound/deploy \
  -H "Content-Type: application/json" \
  -d '{
    "repo": "my-app",
    "branch": "main",
    "status": "succeeded",
    "commit": "abc123"
  }'

Real-World Integration Scenarios

Scenario 1: Message Auditing and Compliance

Send all AI conversation records to your enterprise audit system:

{
  webhooks: {
    endpoints: [{
      name: "audit-log",
      url: "https://audit.company.com/api/logs",
      events: ["message.received", "message.sent"],
      // Only send events for specific Agents
      filter: {
        agentIds: ["customer-support", "hr-assistant"]
      }
    }]
  }
}

Scenario 2: Slack Alert Notifications

Automatically send Slack alerts when the AI Agent encounters an error:

{
  webhooks: {
    endpoints: [{
      name: "slack-alert",
      url: "https://hooks.slack.com/services/T00/B00/xxxxx",
      events: ["error.occurred"],
      // Transform to Slack message format
      transform: {
        text: "🚨 OpenClaw Alert: {{data.error.message}}\nAgent: {{data.agentId}}\nTime: {{timestamp}}"
      }
    }]
  }
}

Scenario 3: CRM System Integration

Automatically create a record in the CRM when a user starts a new chat session:

{
  webhooks: {
    endpoints: [{
      name: "crm-integration",
      url: "https://crm.company.com/api/interactions",
      events: ["session.created"],
      headers: {
        "X-API-Key": "${CRM_API_KEY}"
      }
    }]
  }
}

Scenario 4: Bidirectional Integration with a Ticketing System

Combine incoming and outgoing Webhooks to achieve bidirectional integration between the AI Agent and a ticketing system:

1. User describes an issue via chat -> AI automatically creates a ticket (outgoing Webhook)
2. Ticket status updates -> Notifies the AI Agent (incoming Webhook) -> AI proactively notifies the user

{
  webhooks: {
    // Outgoing: new session -> create ticket
    endpoints: [{
      name: "create-ticket",
      url: "https://ticketing.company.com/api/tickets",
      events: ["session.created"],
      filter: { agentIds: ["support-bot"] }
    }],
    // Incoming: ticket update -> notify Agent
    inbound: {
      endpoints: {
        "ticket-update": {
          agentId: "support-bot",
          template: "Ticket #{{body.ticketId}} status has been updated to: {{body.status}}"
        }
      }
    }
  }
}

Webhook Debugging

Viewing Webhook Send Logs

# View recent Webhook events
openclaw webhooks list --recent 20

# View failed Webhooks
openclaw webhooks list --status failed

Using the Dashboard for Monitoring

OpenClaw's Web Dashboard provides a Webhook monitoring panel where you can view event delivery status, response times, and failure reasons in real time.

Local Testing

Use ngrok or a similar tool to test Webhooks locally:

# Start a local proxy
ngrok http 8080

# Configure the generated URL as the Webhook target
# https://xxxx.ngrok.io/openclaw/events

Summary

OpenClaw's Webhook mechanism bridges the gap between AI Agents and external systems. Through outgoing Webhooks, you can send AI behavioral data to audit systems, monitoring platforms, and business systems; through incoming Webhooks, external events can directly trigger AI Agent responses. This event-driven architecture allows OpenClaw to deeply integrate into your enterprise's technology ecosystem, rather than operating as just a standalone chat tool.