文档API 开放平台Webhook 端点

Webhook 端点

工作流触发 + 审批响应（POST + GET 一键链接）。

Webhook 端点用于「外部系统主动推送事件」。两类：工作流触发（外部系统推送数据 → 拉起工作流执行）和审批回调（外部系统推送决策 → 完成 manual_approval 步骤）。

1. 工作流触发

POST /api/webhooks/{webhookId}/trigger
鉴权: API Key（Bearer / X-API-Key / ?api_key）· Scope: WEBHOOK_TRIGGER

先在控制台创建 Webhook：绑定到目标工作流，并选择一把带 WEBHOOK_TRIGGER 范围的 API Key。之后外部系统向触发 URL POST 一个 JSON 对象（上限 1 MB），payload 顶层字段按 variableMapping 或同名规则映射为工作流变量。

完整的创建步骤、触发 curl 示例、变量映射规则、错误码表和 HMAC 兼容模式，见 Webhook 触发工作流；本页只列开放平台侧的端点契约。

权限边界

双重校验

Webhook 创建时绑定了一个 apiKeyId。触发时，请求 Token 解析出的 Key 必须恰好是绑定的那一把（key id 完全相等），且 Key 与 Webhook 属于同一账号。这保证：即便一把有 WEBHOOK_TRIGGER 范围的 Key 泄漏，它也只能触发显式绑定了它的 Webhook，无法触发别人的工作流。已绑定 API Key 的 Webhook 不再接受 HMAC 签名。

2. 审批响应（POST 方式）

POST /api/webhook-trigger/approval
鉴权: API Key (Bearer) · Scope: APPROVAL_RESPOND

用于在外部系统（自动化逻辑、Slack Bot、邮件回复处理等）中提交审批决策。请求体上限 64 KB。

bash

curl -X POST https://braidrun.com/api/webhook-trigger/approval \
  -H "Authorization: Bearer dyk_<id>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "approvalId": "<approval-id>",
    "decision": "approve",
    "comment": "Approved by CFO via Slack"
  }'

成功响应：

json

{
  "ok": true,
  "approvalId": "<approval-id>",
  "decision": "approve"
}

请求字段

字段	类型	说明
`approvalId`	string	从 manual_approval 步骤事件 / 审批列表 / 通知模板中获取
`decision`	string	"approve" 或 "reject"（不区分大小写）
`comment`	string	可选，记录在审批历史里

错误响应

状态码	含义
`400`	decision 不是 approve / reject
`401`	API Key 无效或缺 APPROVAL_RESPOND 范围
`403`	Key 所有者不是该审批的授权审批人
`404`	审批不存在，或对 Key 所有者不可见
`409`	审批已被处理，不能重复决策
`429`	请求过于频繁，响应带 Retry-After 与 X-RateLimit-* 头

3. 审批一键链接（GET 方式）

GET /api/webhook-trigger/approval/{approvalId}/{decision}?api_key=…
鉴权: API Key（query 参数）· Scope: APPROVAL_RESPOND

为了让审批人在邮件 / Slack / Telegram 里点一下链接就完成审批，提供 GET 形式的端点。响应是 HTML 页面，不是 JSON。

text

https://braidrun.com/api/webhook-trigger/approval/<approval-id>/approve?api_key=dyk_<id>_<secret>
https://braidrun.com/api/webhook-trigger/approval/<approval-id>/reject?api_key=dyk_<id>_<secret>&comment=Need%20more%20info

链接第一次打开只显示确认页，点击页面上的确认按钮（URL 追加 confirm=1）才真正提交决策。邮件客户端和 IM 的链接预览机器人只会抓到确认页，不会误批。

可以把这种链接嵌进审批通知消息，例如：

markdown

## 工作流等待您批准

请审批 [发票 #1234] 的支付。

[批准](https://braidrun.com/api/webhook-trigger/approval/<approval-id>/approve?api_key=<api-key>)
[拒绝](https://braidrun.com/api/webhook-trigger/approval/<approval-id>/reject?api_key=<api-key>)

一键链接的安全约束

给一键审批用的 API Key 应当设置较短有效期（建议 24-72 小时）
Scope 严格限制到 APPROVAL_RESPOND，不要混用其他权限
链接转发出去等同于把审批权交出去——不要在群组里贴明文链接，最好通过私信
万一链接泄漏：进控制台立即吊销该 Key，已被批准/拒绝的审批可以通过审计日志追溯

HMAC 签名（兼容旧集成）

未绑定 API Key、只配置了 secretKey 的 Webhook 仍走 HMAC-SHA256 共享密钥模式（请求头 X-Webhook-Signature）。一旦给 Webhook 绑定 API Key，HMAC 就不再被接受，迁移是单向的。新集成请直接用 API Key 模式；签名算法与迁移细节见 Webhook 触发工作流。