Webhook 触发

Webhook 让外部系统（GitHub、CI/CD、Lark、IoT、上游 API）通过 HTTP POST 直接拉起工作流执行。推荐做法：给 Webhook 绑定一个带 WEBHOOK_TRIGGER 权限范围的 API Key，触发请求用这个 Key 鉴权。

创建 Webhook 并绑定 API Key

1. 在 控制台 → 账号设置 → API 密钥 新建一个 Key，scope 勾选 WEBHOOK_TRIGGER （详见API Key 与权限范围）
2. 在 Webhook 列表或工作流详情页新建 Webhook，选择目标工作流并绑定这个 Key。创建者需要对工作流有编辑权限，绑定的 Key 必须是自己名下的

也可以走管理 API（控制台登录态）：

curl -X POST https://braidrun.com/api/webhooks \
  -H "Authorization: Bearer <console-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "workflowId": "<workflow-id>",
    "name": "GitHub Push Webhook",
    "apiKeyId": "<api-key-id>",
    "variableMapping": {
      "branch": "ref",
      "repo_name": "repo"
    }
  }'

响应中包含一个唯一的 webhook-id，触发 URL 为：

POST https://braidrun.com/api/webhooks/<webhook-id>/trigger

Webhook 数量随套餐：Pro 3 个、Team 10 个。

触发工作流

curl -X POST https://braidrun.com/api/webhooks/<webhook-id>/trigger \
  -H "Authorization: Bearer dyk_<id>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "ref": "refs/heads/main",
    "repo": "my-app"
  }'

凭据有三种携带方式，服务端按以下顺序识别：

Authorization: Bearer dyk_<id>_<secret>      # 推荐
X-API-Key: dyk_<id>_<secret>                  # 无法自定义 Authorization 头时
POST .../trigger?api_key=dyk_<id>_<secret>    # 仅限无法设置 header 的场景

成功触发返回：

{
  "executionId": "exec_a3b9c8...",
  "webhookId": "<webhook-id>",
  "workflowId": "<workflow-id>",
  "status": "PENDING",
  "startedAt": 1735632891234
}

变量映射

不配置 variableMapping 时，payload 顶层的字符串 / 数字 / 布尔字段会按同名自动映射为工作流变量；嵌套对象和数组不参与自动映射。

需要改名时配置 variableMapping ：键是工作流变量名，值是 payload 顶层字段名。只支持顶层字段，不支持嵌套路径取值。

# Webhook 配置
"variableMapping": { "branch": "ref", "repo_name": "repo" }

# 触发 payload
{ "ref": "refs/heads/main", "repo": "my-app" }

# 工作流实际拿到的输入
{ "branch": "refs/heads/main", "repo_name": "my-app" }

payload 里缺少被映射的字段时，该变量不会注入，工作流模板里的默认值继续生效（不会被空字符串覆盖）。

HMAC 签名（兼容旧集成）

未绑定 API Key、但设置了 secretKey 的 Webhook 走旧版 HMAC 模式：触发请求必须在 header 中携带签名：

X-Webhook-Signature: sha256=<hex(HMAC-SHA256(rawRequestBody, secretKey))>

签名 = HmacSHA256(rawRequestBody, secretKey) ，输出 hex 字符串，sha256= 前缀可带可不带。比对失败返回 401。

已绑定 API Key 的 Webhook 不再接受 HMAC 签名（即使 secretKey 字段仍有值），迁移到 API Key 是单向的。两种认证都未配置的 Webhook 触发时不校验身份，URL 本身就等于凭据，只建议在调试阶段这样用。

旧版触发路径 POST /api/webhook-trigger/{webhookId} 仍然保留，行为一致；新集成请使用上面的规范路径。

错误响应

常见接入场景

• GitHub push — 把分支名、提交作者映射成变量；workflow 自动 build / test / deploy
• CI 系统 — 构建完成 → Webhook 触发后续发布流水线
• Lark / 飞书机器人 — 收到特定 command 后触发运营批处理
• IoT 上报 — 设备告警 → Webhook 触发排查 workflow 并收敛告警

管理端点

列表 GET /api/webhooks、更新 PUT /api/webhooks/{id}、删除 DELETE /api/webhooks/{id}，另有 GET /api/webhooks/{id}/stats 返回触发统计；这些都是控制台登录态接口。

服务重启时

Webhook 触发的 execution 被服务重启中断后不会自动续跑：payload 按 at-most-once 处理，平台不做重放。已停在 manual_approval 等待审批的执行是例外，审批通过后照常继续。需要补跑时由上游重新发一次触发请求即可（会创建一条新的 execution）。

相关页面

• 开放平台 Webhook 端点（审批回调）
• API Key 与权限范围