使用 webhooks 将 Clawdbot AI 助手与外部服务集成。了解如何接收和发送 webhook 事件以实现自动化。

Clawdbot Webhooks 概述

Clawdbot 支持用于与外部服务集成的 webhooks。Webhooks 支持事件驱动的自动化、外部触发器和服务到服务的通信。

传入 Webhooks

配置

{
  "webhooks": {
    "incoming": {
      "enabled": true,
      "port": 3011,
      "secret": "your-webhook-secret"
    }
  }
}

端点

POST http://localhost:3011/webhook/<hook-id>

认证

curl -X POST http://localhost:3011/webhook/my-hook \
  -H "X-Webhook-Secret: your-webhook-secret" \
  -H "Content-Type: application/json" \
  -d '{"message": "来自外部服务的消息"}'

Webhook 处理器

定义处理器

{
  "webhooks": {
    "handlers": [
      {
        "id": "github-events",
        "path": "/github",
        "action": "run_agent",
        "agentId": "devops",
        "template": "新的 GitHub 事件: {{event.action}} 在 {{event.repository.name}}"
      }
    ]
  }
}

处理器动作

动作	描述
`send_message`	发送消息到频道
`run_agent`	使用提示触发代理
`forward`	转发到另一个端点
`custom`	自定义处理函数

会话处理

Webhook 会话键

Webhooks 使用专用会话：

hook:<uuid>

会话选项

{
  "webhooks": {
    "handlers": [
      {
        "id": "alerts",
        "sessionMode": "persistent",
        "sessionKey": "alerts-session"
      }
    ]
  }
}

传出 Webhooks

配置

{
  "webhooks": {
    "outgoing": [
      {
        "id": "slack-notify",
        "url": "https://hooks.slack.com/services/xxx",
        "events": ["message_received", "agent_response"],
        "method": "POST"
      }
    ]
  }
}

事件类型

事件	描述
`message_received`	新消息到达
`agent_response`	代理生成响应
`session_started`	新会话创建
`session_ended`	会话过期/关闭
`error`	发生错误

负载格式

传入负载

{
  "event": "custom_event",
  "data": {
    "key": "value"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

传出负载

{
  "type": "message_received",
  "session": "agent:main:whatsapp",
  "message": {
    "from": "+15551234567",
    "text": "你好",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

安全性

密钥验证

{
  "webhooks": {
    "incoming": {
      "secretHeader": "X-Webhook-Secret",
      "secret": "your-secret"
    }
  }
}

IP 白名单

{
  "webhooks": {
    "incoming": {
      "allowedIPs": [
        "192.168.1.0/24",
        "10.0.0.1"
      ]
    }
  }
}

错误处理

重试配置

{
  "webhooks": {
    "outgoing": [
      {
        "id": "notify",
        "retry": {
          "maxAttempts": 3,
          "backoff": "exponential"
        }
      }
    ]
  }
}

失败处理

记录失败的 webhooks
使用指数退避重试
可选的死信队列

示例

GitHub 集成

{
  "webhooks": {
    "handlers": [
      {
        "id": "github",
        "path": "/github",
        "action": "send_message",
        "target": {
          "channel": "discord",
          "peer": "dev-channel"
        },
        "template": "🔔 {{event.action}}: {{event.pull_request.title}}"
      }
    ]
  }
}

告警转发

{
  "webhooks": {
    "handlers": [
      {
        "id": "alerts",
        "path": "/alerts",
        "action": "run_agent",
        "agentId": "oncall",
        "template": "告警: {{alert.name}} - {{alert.message}}"
      }
    ]
  }
}

下一步

Clawdbot 定时任务 - 计划任务
Clawdbot 网关 - 网关配置
Clawdbot 工具 - 工具配置

Clawdbot Webhooks

On this page