#Webhooks API

通过 Webhook 订阅平台事件，实现实时通知和集成。

基础路径: /v1/webhooks

#Webhook 管理

#创建 Webhook

POST /v1/webhooks

所需权限: write

#请求体

json{
  "url": "https://your-server.com/webhook",
  "events": [
    "agent.created",
    "agent.updated",
    "agent.deleted",
    "document.uploaded",
    "document.processed",
    "document.deleted",
    "knowledge_base.created",
    "knowledge_base.updated",
    "knowledge_base.deleted"
  ],
  "secret": "your-webhook-secret",
  "active": true
}

字段	类型	必填	说明
`url`	string	是	Webhook 接收 URL
`events`	string[]	是	订阅的事件列表
`secret`	string	否	签名密钥，用于验证请求来源
`active`	boolean	否	是否激活，默认 true

#响应

HTTP 201 Created

#列出 Webhook

GET /v1/webhooks

所需权限: read

#响应

json{
  "data": [
    {
      "id": "wh_abc123",
      "url": "https://your-server.com/webhook",
      "events": ["agent.created", "agent.updated"],
      "active": true,
      "createdAt": "2026-01-10T08:00:00Z",
      "updatedAt": "2026-02-15T12:00:00Z"
    }
  ],
  "meta": {
    "total": 1
  }
}

#获取 Webhook 详情

GET /v1/webhooks/:id

所需权限: read

#更新 Webhook

PUT /v1/webhooks/:id

所需权限: admin

#请求体

json{
  "url": "https://new-server.com/webhook",
  "events": ["agent.created"],
  "active": false
}

#删除 Webhook

DELETE /v1/webhooks/:id

所需权限: admin

#响应

HTTP 204 No Content

#投递管理

#获取投递历史

GET /v1/webhooks/:id/deliveries

所需权限: read

#查询参数

参数	类型	说明
`limit`	number	返回条数，默认 50，最大 100

#响应

json{
  "data": [
    {
      "id": "delivery_xxx",
      "webhookId": "wh_abc123",
      "event": "agent.created",
      "status": "success",
      "statusCode": 200,
      "payload": { "agent": { "id": "agent_xxx", "name": "..." } },
      "response": "OK",
      "duration": 250,
      "attemptCount": 1,
      "createdAt": "2026-02-20T08:00:00Z"
    }
  ],
  "meta": {
    "total": 1
  }
}

#获取投递统计

GET /v1/webhooks/:id/deliveries/stats

所需权限: read

#响应

json{
  "total": 150,
  "successful": 145,
  "failed": 5,
  "successRate": 96.67,
  "avgDuration": 180
}

#支持的事件

#Agent 事件

事件名称	说明
`agent.created`	Agent 创建
`agent.updated`	Agent 配置更新
`agent.deleted`	Agent 删除

#Chat / Session 事件

事件名称	说明
`session.created`	聊天会话创建
`message.created`	聊天消息创建（包括用户和助手消息）

#知识库事件

事件名称	说明
`knowledge_base.created`	知识库创建
`knowledge_base.updated`	知识库配置更新
`knowledge_base.deleted`	知识库删除

#文档事件

事件名称	说明
`document.uploaded`	文档上传
`document.processed`	文档处理完成（向量化成功）
`document.deleted`	文档删除

#Skill 事件

事件名称	说明
`skill.published`	Skill 发布
`skill.installed`	Skill 安装到 Agent

#认证事件

事件名称	说明
`user.created`	新用户注册
`login.failed`	登录失败
`account.locked`	账户被锁定
`api_key.created`	API Key 创建

#账单事件

事件名称	说明
`subscription.created`	订阅创建
`subscription.updated`	订阅更新（升级/降级）
`invoice.paid`	发票支付完成
`budget_alert.triggered`	预算预警触发
`budget.threshold_exceeded`	预算阈值超出

#导入任务事件

事件名称	说明
`import_job.completed`	导入任务完成
`import_job.failed`	导入任务失败
`import_job.partially_failed`	导入任务部分失败

#Webhook 负载格式

每次事件触发时，系统会向注册的 URL 发送 POST 请求：

POST https://your-server.com/webhook
Content-Type: application/json
X-Webhook-Signature: sha256=...

json{
  "event": "agent.created",
  "timestamp": "2026-02-20T08:00:00Z",
  "data": {
    "agent": {
      "id": "agent_xxx",
      "name": "新助手",
      "model": "zhipu/glm-4"
    }
  }
}

#签名验证

如果创建 Webhook 时提供了 secret，每次投递会在请求头中包含 X-Webhook-Signature，使用 HMAC-SHA256 算法对请求体进行签名。

验证示例（Node.js）：

javascriptconst crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
}

#重试策略

当 Webhook 投递失败（HTTP 状态码 >= 400 或超时）时，系统会按以下策略重试：

第 1 次重试：延迟 1 分钟
第 2 次重试：延迟 5 分钟
第 3 次重试：延迟 30 分钟

3 次重试后仍失败则标记为 failed，可通过投递历史查看详情。