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 頂層的字串 / 數字 / 布林欄位會依同名自動對應為 workflow 變數；巢狀物件與陣列不參與自動對應。

需要更名時設定 variableMapping ：鍵是 workflow 變數名，值是 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 裡缺少被對應的欄位時，該變數不會注入，workflow 範本裡的預設值繼續生效（不會被空字串覆寫）。

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 與權限範圍