LobeHub 开发者 Webhook
即将推出(#23272)。开发者 Webhook 尚未上线 LobeHub Cloud。本页介绍该 PR 中实现的投递格式和签名方案,方便你提前准备接收端;正式发布前,名称和限制仍可能调整。
Webhook 端点是你提供的一个 URL。当你的个人空间或工作区中发生特定事件(例如运行结束、消息创建、文件解析完成)时,LobeHub 会向它发送一个带签名的 POST 请求。端点通过 /api/v1/webhooks 管理,需要 webhook:read 和 webhook:write scope;也可以在应用的 设置 → Webhook 中管理,该页面由同一 PR 添加。
管理端点
| 方法与路径 | 用途 |
|---|---|
GET /webhooks | 列出端点(游标分页) |
POST /webhooks | 创建端点:url、events,可选 description 和 enabled。响应中包含签名密钥,仅在此处显示 |
GET /webhooks/{id} | 读取端点 |
PATCH /webhooks/{id} | 修改 URL、事件、描述,或重新启用端点 |
DELETE /webhooks/{id} | 删除端点 |
POST /webhooks/{id}/rotate-secret | 签发新的签名密钥(仅显示一次) |
POST /webhooks/{id}/test | 发送一个 webhook.test 事件 |
GET /webhooks/{id}/deliveries | 投递日志 |
POST /webhooks/{id}/deliveries/{deliveryId}/redeliver | 重新发送一次历史投递,事件 id 和请求体保持不变 |
每个空间最多可创建 20 个端点。订阅某个事件还需要该事件数据的读取 scope,例如订阅 run.* 需要 run:read;否则请求返回 403 insufficient_scope。
事件目录
| 事件 | 触发时机 | data | 读取 scope |
|---|---|---|---|
run.started | Agent 运行开始 | { runId, agentId, topicId } | run:read |
run.completed | 运行结束 | 运行字段,外加 assistantMessageId、steps | run:read |
run.failed | 运行失败 | 运行字段,外加 error | run:read |
run.intervention_requested | 运行等待人工审批 | { runId, agentId, topicId } | run:read |
message.created | 创建了一条消息 | { messageId, role, topicId, threadId, agentId } | chat:read |
topic.created | 创建了一个话题 | { topicId, title, agentId } | chat:read |
task.status_changed | 任务状态变化 | { taskId, identifier, status, previousStatus } | agent:read |
goal.status_changed | 目标状态变化 | { goalId, status, previousStatus } | agent:read |
file.parsed | 文件解析完成 | { fileId, name, status: "success" | "error", error } | file:read |
notification.created | 创建了一条通知 | { notificationId, category, type, title } | user:read |
webhook.test | 调用 POST /webhooks/{id}/test 时 | { webhookId, message } | 不可订阅 |
投递格式
id在重试和重新投递时保持不变,可用它忽略重复事件。- 来自个人空间的事件,
workspaceId为null。 - 只有
2xx响应才算投递成功,不跟随重定向。请在 10 秒内响应,耗时操作放到响应之后处理。
重试
投递失败后最多共尝试 6 次,每次间隔依次为 30 秒、2 分钟、8 分钟、32 分钟和约 2 小时。如果连续 5 次投递的所有尝试都失败,端点会被停用;修复接收端后,用 PATCH /webhooks/{id} 重新启用。测试投递只尝试一次。
校验签名
每次投递都使用端点的签名密钥(whsec_…)签名:
- HMAC 的密钥是完整的签名密钥字符串,包括
whsec_前缀。 - 被签名的字符串由时间戳请求头、一个点号和收到的原始请求体拼接而成。解析后再序列化 JSON 会改变内容,导致签名不匹配。
- 拒绝与本地时钟相差超过 300 秒的时间戳,防止截获的请求在之后被重放。
- 请求头中可以包含多个
v1=值,以空格或逗号分隔,例如刚轮换签名密钥之后。只要其中任意一个匹配,就接受该请求。 - 使用常量时间比较。
Node.js
使用 Express 时,需要在任何 JSON 解析器之前读取原始请求体:app.post('/lobehub/webhook', express.raw({ type: 'application/json' }), …),然后传入 req.body.toString('utf8') 和 req.headers。
Python
请求头名称需转为小写后传入(Flask:{k.lower(): v for k, v in request.headers.items()}),请求体取自 request.get_data()。
使用 TypeScript SDK
同一个 PR 为 @lobehub/sdk 增加了校验辅助函数,支持 Fetch Headers 和 Node 请求头对象:
verifyWebhookSignature 只校验、不解析。两者都会抛出 WebhookSignatureVerificationError,其 code 取值如 missing_signature、timestamp_out_of_range 或 signature_mismatch。
聊天平台的 Webhook 渠道
另一个 PR #23332(即将推出)新增了 Custom Webhook 渠道,可将任意聊天平台连接到 Agent,并提供 /api/v1/bots(bot:read、bot:write)用于管理机器人。其入站和出站消息使用相同的 X-LobeHub-Timestamp 与 X-LobeHub-Signature 方案,并以机器人自己的签名密钥签名。