使用 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": "Hello from external service"}'

Webhook 處理器

定義處理器

{
  "webhooks": {
    "handlers": [
      {
        "id": "github-events",
        "path": "/github",
        "action": "run_agent",
        "agentId": "devops",
        "template": "New GitHub event: {{event.action}} on {{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": "Hello",
    "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: {{alert.name}} - {{alert.message}}"
      }
    ]
  }
}

下一步

Clawdbot 定時任務 - 排程任務
Clawdbot 網關 - 網關配置
Clawdbot 工具 - 工具配置

Clawdbot Webhooks

On this page