API 参考: 事件 (Events)

事件订阅与 Webhook 管理端点。

注册 Webhook 订阅

订阅指定事件，当事件发生时平台向目标 URL 发送 POST 请求。

POST /v1/events/webhooks

权限要求： write

请求体

字段	类型	必填	说明
event	string	是	事件类型（见下方列表）
url	string	是	Webhook 接收地址
secret	string	否	用于 HMAC-SHA256 签名验证的密钥
filter	object	否	过滤条件，仅投递匹配的事件

可用事件类型

事件	说明
app.installed	应用安装
app.configured	应用配置完成
tool.executed	工具执行成功
tool.failed	工具执行失败
knowledge.updated	知识库更新
graph.synced	图谱同步完成
workflow.completed	工作流执行成功
workflow.failed	工作流执行失败
alert.triggered	报警触发
ai.conversation	AI 对话完成

请求示例

curl -X POST https://api.invoratec.cn/v1/events/webhooks \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "workflow.completed",
    "url": "https://my-server.com/webhooks/workflow",
    "secret": "my-webhook-secret",
    "filter": {}
  }'

响应 (201 Created)

{
  "id": "665f1a2b3c4d5e6f7a8b9c0d",
  "developerId": "user_123",
  "event": "workflow.completed",
  "url": "https://my-server.com/webhooks/workflow",
  "filter": {},
  "enabled": true,
  "createdAt": "2026-04-12T08:00:00.000Z",
  "lastTriggered": null,
  "failCount": 0
}

错误

状态码	说明
400	event 或 url 缺失，或事件类型无效
403	缺少 write 权限

---

列出 Webhook 订阅

GET /v1/events/webhooks

请求示例

curl https://api.invoratec.cn/v1/events/webhooks \
  -H "X-API-Key: claw_xxxx"

响应

{
  "webhooks": [
    {
      "_id": "665f...",
      "event": "workflow.completed",
      "url": "https://my-server.com/webhooks/workflow",
      "enabled": true,
      "lastTriggered": "2026-04-12T09:00:00.000Z",
      "failCount": 0,
      "createdAt": "2026-04-12T08:00:00.000Z"
    }
  ],
  "eventTypes": [
    "app.installed", "app.configured",
    "tool.executed", "tool.failed",
    "knowledge.updated", "graph.synced",
    "workflow.completed", "workflow.failed",
    "alert.triggered", "ai.conversation"
  ]
}

响应中同时返回 eventTypes 列表，方便客户端展示可选事件。

---

删除 Webhook 订阅

DELETE /v1/events/webhooks/{id}

路径参数

参数	类型	说明
id	string	Webhook _id

请求示例

curl -X DELETE https://api.invoratec.cn/v1/events/webhooks/665f... \
  -H "X-API-Key: claw_xxxx"

响应

{ "success": true }

---

列出事件类型

获取所有可订阅的事件类型列表。

GET /v1/events/types

请求示例

curl https://api.invoratec.cn/v1/events/types \
  -H "X-API-Key: claw_xxxx"

响应

{
  "eventTypes": [
    "app.installed",
    "app.configured",
    "tool.executed",
    "tool.failed",
    "knowledge.updated",
    "graph.synced",
    "workflow.completed",
    "workflow.failed",
    "alert.triggered",
    "ai.conversation"
  ]
}

---

查看事件日志

获取 API 调用日志记录，按时间倒序排列。

GET /v1/events/logs

查询参数

参数	类型	说明
limit	integer	返回上限，默认 100

请求示例

curl "https://api.invoratec.cn/v1/events/logs?limit=50" \
  -H "X-API-Key: claw_xxxx"

响应

{
  "logs": [
    {
      "_id": "665f...",
      "userId": "user_123",
      "endpoint": "/v1/ai/chat",
      "method": "POST",
      "status": 200,
      "timestamp": "2026-04-12T09:00:00.000Z",
      "responseTime": 1500
    },
    {
      "_id": "665e...",
      "userId": "user_123",
      "endpoint": "/v1/tools/erp_get_inventory/test",
      "method": "POST",
      "status": 200,
      "timestamp": "2026-04-12T08:30:00.000Z",
      "responseTime": 230
    }
  ]
}

---

Webhook 投递格式

当事件触发时，平台向订阅的 URL 发送如下格式的 POST 请求：

请求头

Content-Type: application/json
X-Webhook-Event: tool.executed
X-Webhook-Timestamp: 2026-04-12T08:00:00.000Z
X-Webhook-Signature: sha256=abc123def456...

X-Webhook-Signature 仅在注册时设置了 secret 时才会出现。签名算法为 HMAC-SHA256，签名内容为请求体的原始 JSON 字符串。

请求体

{
  "event": "tool.executed",
  "timestamp": "2026-04-12T08:00:00.000Z",
  "data": {
    "toolName": "erp_get_inventory",
    "input": { "warehouse_id": "WH-001" },
    "result": { "items": [...], "total": 42 },
    "elapsed_ms": 230
  }
}

各事件的 data 字段

事件	data 内容
tool.executed	toolName, input, result, elapsed_ms
tool.failed	toolName, input, error
workflow.completed	workflowId, workflowName, runId, status, stepResults
workflow.failed	workflowId, workflowName, runId, error
knowledge.updated	knowledgeId, action (upload/update), documentTitle
graph.synced	graphId, nodesWritten, edgesWritten
alert.triggered	alertType, source, message, severity
ai.conversation	model, inputTokens, outputTokens
app.installed	appId, appName
app.configured	appId, appName

签名验证

import hmac, hashlib

def verify(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

const crypto = require('crypto')

function verify(body, signature, secret) {
  const expected = crypto.createHmac('sha256', secret).update(body).digest('hex')
  return signature === `sha256=${expected}`
}