OpenClaw Webhook統合とイベントコールバック

はじめに

実際の本番環境では、AI Agent は単独で動作するものではありません——企業の既存システムとの双方向統合が必要です。OpenClaw は完全な Webhook メカニズムを提供しており、特定のイベントが発生した際に外部システムにコールバック通知を送信したり、外部システムからのイベントを受信して Agent のアクションをトリガーしたりできます。

本記事では、OpenClaw の Webhook 統合方式を包括的に紹介し、イベント駆動型の AI ワークフローの構築をサポートします。

Webhook の基本概念

OpenClaw の Webhook システムは 2 つの方向に分かれます。

アウトバウンド Webhook（Outgoing）：OpenClaw 内部で特定のイベントが発生した際に、設定された URL に HTTP POST リクエストを送信
インバウンド Webhook（Incoming）：外部システムが HTTP リクエストを通じて OpenClaw の Agent にタスクの実行をトリガー

アウトバウンドフロー：
  OpenClaw イベント → HTTP POST → あなたのサーバー

インバウンドフロー：
  あなたのサーバー → HTTP POST → OpenClaw → Agent 処理 → コールバック通知

アウトバウンド Webhook の設定

基本設定

openclaw.json5 に Webhook 設定を追加します。

{
  webhooks: {
    endpoints: [
      {
        // Webhook 名称
        name: "main-webhook",
        // ターゲット URL
        url: "https://your-server.com/openclaw/events",
        // 署名シークレット（リクエストの真正性を検証するために使用）
        secret: "whsec_xxxxxxxxxxxxxxxx",
        // 購読するイベントタイプ
        events: [
          "message.received",
          "message.sent",
          "session.created",
          "session.ended",
          "tool.called",
          "tool.completed",
          "error.occurred"
        ],
        // リトライ設定
        retry: {
          maxAttempts: 3,
          backoffMs: 1000
        }
      }
    ]
  }
}

イベントタイプの詳細

イベントタイプ	トリガータイミング	用途
`message.received`	ユーザーメッセージの受信時	ログ記録、メッセージ監査
`message.sent`	AI 返信の送信後	返信監視、コンテンツ審査
`session.created`	新しいセッションの作成時	ユーザー行動トラッキング
`session.ended`	セッションの終了またはタイムアウト時	データアーカイブ
`tool.called`	MCP ツールの呼び出し時	セキュリティ監査
`tool.completed`	ツール呼び出しの完了時	パフォーマンス監視
`error.occurred`	エラー発生時	アラート通知

イベントペイロードフォーマット

各 Webhook リクエストの Body は統一フォーマットに従います。

{
  "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": "これはAIの返信内容です...",
      "messageId": "msg_xyz789"
    },
    "model": "claude-sonnet-4-20250514",
    "usage": {
      "inputTokens": 200,
      "outputTokens": 450
    }
  }
}

署名検証

Webhook リクエストが確かにあなたの OpenClaw インスタンスからのものであることを確認するために、各リクエストには署名ヘッダーが付加されます。

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

検証例（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;
}

インバウンド Webhook の設定

インバウンド Webhook により、外部システムが OpenClaw の Agent を能動的にトリガーできます。

{
  webhooks: {
    inbound: {
      enabled: true,
      // インバウンド Webhook パスプレフィックス
      basePath: "/webhooks/inbound",
      // エンドポイント設定
      endpoints: {
        // POST /webhooks/inbound/alert を受信した際にトリガー
        "alert": {
          agentId: "alert-handler",
          // メッセージテンプレート、変数置換をサポート
          template: "アラートを受信：{{body.title}} - 重大度：{{body.severity}}"
        },
        "deploy": {
          agentId: "devops-agent",
          template: "{{body.repo}} の {{body.branch}} ブランチのデプロイが{{body.status}}"
        }
      }
    }
  }
}

外部システムからの呼び出し例:

# CI/CD デプロイ通知
curl -X POST http://openclaw.example.com/webhooks/inbound/deploy \
  -H "Content-Type: application/json" \
  -d '{
    "repo": "my-app",
    "branch": "main",
    "status": "成功",
    "commit": "abc123"
  }'

実際の統合シーン

シーン1：メッセージ監査とコンプライアンス

すべての AI 対話記録を企業の監査システムに送信します。

{
  webhooks: {
    endpoints: [{
      name: "audit-log",
      url: "https://audit.company.com/api/logs",
      events: ["message.received", "message.sent"],
      // 特定の Agent のイベントのみ送信
      filter: {
        agentIds: ["customer-support", "hr-assistant"]
      }
    }]
  }
}

シーン2：Slack アラート通知

AI Agent がエラーに遭遇した際に、自動的に Slack アラートを送信します。

{
  webhooks: {
    endpoints: [{
      name: "slack-alert",
      url: "https://hooks.slack.com/services/T00/B00/xxxxx",
      events: ["error.occurred"],
      // Slack メッセージフォーマットに変換
      transform: {
        text: "🚨 OpenClaw アラート: {{data.error.message}}\nAgent: {{data.agentId}}\n時刻: {{timestamp}}"
      }
    }]
  }
}

シーン3：CRM システム統合

ユーザーがチャットで新しいセッションを開始した際に、CRM に自動的にレコードを作成します。

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

シーン4：双方向統合——チケットシステム

インバウンドとアウトバウンドの Webhook を組み合わせて、AI Agent とチケットシステムの双方向連携を実現します。

ユーザーがチャットで問題を説明 → AI が自動的にチケットを作成（アウトバウンド Webhook）
チケットステータスの更新 → AI Agent に通知（インバウンド Webhook）→ AI がユーザーに能動的に通知

{
  webhooks: {
    // アウトバウンド：新規セッション → チケット作成
    endpoints: [{
      name: "create-ticket",
      url: "https://ticketing.company.com/api/tickets",
      events: ["session.created"],
      filter: { agentIds: ["support-bot"] }
    }],
    // インバウンド：チケット更新 → Agent に通知
    inbound: {
      endpoints: {
        "ticket-update": {
          agentId: "support-bot",
          template: "チケット #{{body.ticketId}} のステータスが更新されました：{{body.status}}"
        }
      }
    }
  }
}

Webhook のデバッグ

Webhook 送信ログの確認

# 最近の Webhook イベントを表示
openclaw webhooks list --recent 20

# 失敗した Webhook を表示
openclaw webhooks list --status failed

Dashboard での監視

OpenClaw の Web Dashboard には Webhook 監視パネルがあり、イベントの送信状態、レスポンス時間、失敗原因をリアルタイムで確認できます。

ローカルテスト

ngrok や類似のツールを使用してローカルで Webhook をテストします。

# ローカルプロキシを起動
ngrok http 8080

# 生成された URL を Webhook ターゲットとして設定
# https://xxxx.ngrok.io/openclaw/events

まとめ

OpenClaw の Webhook メカニズムは、AI Agent と外部システム間の橋渡しとなります。アウトバウンド Webhook を通じて、AI の行動データを監査システム、監視プラットフォーム、ビジネスシステムに送信できます。インバウンド Webhook を通じて、外部イベントが AI Agent の応答を直接トリガーできます。このイベント駆動アーキテクチャにより、OpenClaw は企業のテクノロジーエコシステムに深く統合でき、単なる独立したチャットツールにとどまりません。