文件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 觸發工作流。