跳至內容

Webhooks

Webhooks 讓你的系統能在 Tuist 內部發生變更時立即做出反應。每當相關事件發生——例如偵測到新的測試案例、預覽完成上傳,或不穩定測試獲得修復——Tuist 會向每個已訂閱該事件類型的端點發出 HTTP POST 請求。請求本體是一個 JSON 信封,每次傳送都帶有簽章標頭,你可以使用端點的簽署密鑰進行驗證。

你註冊目標 URL,選擇想要的事件,Tuist 會處理簽署、重試以及傳送審核記錄。

接收 Webhooks 的步驟#

你可以透過以下步驟開始在應用程式中接收事件通知:

  1. 識別應用程式想要接收的事件。
  2. 建立 Webhook 端點,作為本地伺服器上的 HTTP 端點(URL)。
  3. 透過解析負載並回傳2xx 狀態碼來處理來自 Tuist 的請求,以便 Tuist 將傳送標記為成功。
  4. 驗證每個請求的簽章,以證明其來自 Tuist。
  5. 使用 Tuist 儀表板中的事件記錄在建置期間進行除錯。

事件類型#

Tuist 根據事件所描述的資源對其進行分組。信封中的 type 欄位使用點號表示法({resource}.{action}),與你在儀表板中訂閱的值相同。

Type When it fires
test_case.created A test case was observed for the first time in this account.
test_case.updated A test case's attributes changed.
preview.created A new preview was created in this account.
preview.deleted A preview was deleted from this account.
runner_job.started A runner started a job created through the runners API.
runner_job.completed A job created through the runners API completed, failed or was cancelled.

未來將提供更多事件類型。如果你需要我們尚未發出的事件類型,請告訴我們,我們會將其加入目錄。

建立端點#

端點是依帳戶設定的。從帳戶設定中開啟Webhooks,點擊新增端點,並提供:

  • 名稱 — 端點在列表中顯示的方式。
  • 端點 URL — 必須使用 https://。
  • 要監聽的事件 — 選擇特定事件,或在群組層級使用全選。只有當已訂閱的事件觸發時,Tuist 才會向端點發送 POST 請求。

端點列表,顯示兩個 Webhook 端點各訂閱了兩個事件

儲存時,Tuist 會產生一個全新的簽署密鑰並僅顯示一次。請立即將其複製到應用程式的設定中——你無法再從儀表板取回它。如果遺失,請使用端點動作選單中的輪替密鑰來發行新的密鑰。

Webhook 端點建立對話框,包含名稱、URL 和分組的事件類型核取方塊

負載#

每次傳送都是一個單獨的 JSON 物件。信封將特定事件的資源快照包裝在元資料中,你可以利用這些元資料進行去重、路由和審核傳送:

欄位 說明
id 此次傳送專屬的 UUID。當重試觸發時,可使用它進行去重。
type 點號表示的事件類型,例如 test_case.updated。
created Tuist 將傳送加入佇列時的 Unix 時間戳記(秒)。
object 資源快照。其結構取決於事件類型。

每種事件類型的確切負載結構記錄在 Tuist API 參考文件 的 Webhook 事件 章節下——每個事件在 components.schemas 下都有對應的 WebhookXxxEvent 結構,你可以從程式碼產生器中 $ref 引用。

例如,test_case.updated 負載還帶有一個 events 陣列,列出導致寫入的標準轉換(marked_flaky、muted、unskipped…),以及 actor_id 和 alert_id,以便接收者區分手動編輯與自動化驅動的變更。

每個請求還攜帶以下 HTTP 標頭:

標頭 說明
Content-Type 始終為 application/json。
User-Agent Tuist-Webhooks/1.0.
Tuist-Event-Id 與本體中的 id 相同的 UUID——如果你在解析負載之前記錄標頭,這會很方便。
Tuist-Event-Type 與本體中的 type 相同的字串。
Tuist-Signature HMAC-SHA256 簽章,格式為 t={timestamp},v1={hex_digest}——見下文。

回應 Webhook#

為了確認收到傳送,你的端點應回傳任何 2xx 狀態碼。2xx 範圍之外的任何內容——以及連線失敗和逾時——都會被視為傳送失敗並進行重試。Tuist 不會追蹤 3xx 回應,因此請直接在規範 URL 上回應,而不是重新導向。

讓你的處理常式保持快速:Tuist 最多等待 10 秒以取得回應。如果你有繁重的工作要執行(呼叫其他 API、更新資料庫、發送通知),請先接受請求並異步處理。提早回傳也能讓你對下游服務的暫時性緩慢更具韌性。

驗證簽章#

任何得知你端點 URL 的人都可以向其發送 POST 請求。簽署密鑰讓你的伺服器能夠拒絕非來自 Tuist 的任何請求。

對於每個請求,Tuist 會計算:

plaintext
signed_payload = "{timestamp}.{raw_request_body}"
signature = HMAC-SHA256(signing_secret, signed_payload)
header = "t={timestamp},v1={hex(signature)}"

要在你的側進行驗證:

  1. 讀取 Tuist-Signature 標頭,並將其拆分為 t=(時間戳記)和 v1=(十六進位摘要)部分。
  2. 如果時間戳記與你伺服器的當前時間相差超過 5 分鐘,則拒絕該請求。這為重放視窗設定了邊界,但並未完全關閉它——請結合下方的冪等性使用。
  3. 重新計算 HMAC-SHA256(signing_secret, "{timestamp}.{raw_body}") 並以恆定時間與摘要進行比較。
  4. 根據負載 id(也顯示為 Tuist-Event-Id 標頭)對傳送進行去重。它在重試過程中保持穩定,因此持久化你已處理的 ID 可以防止被捕獲的請求在容差視窗內被重放,並保護你在重試時不會重複處理。
USE THE RAW BODY

簽章是根據 Tuist 發送的字節計算的。如果你的 Web 框架在驗證之前重新解析並重新序列化 JSON,摘要將無法匹配。捕獲原始本體(例如 Rack 中的 request.body.read,Express 中的原始 Buffer)並將其傳遞給你的驗證器。

Node.js 中的參考驗證器——將相同的四個步驟(解析標頭、檢查時間戳記偏移、重新計算 HMAC、以恆定時間比較)轉換為你接收器所使用的語言:

javascript
import crypto from "node:crypto";
function verifyTuistSignature(rawBody, header, secret, toleranceSeconds = 300) {
const parts = Object.fromEntries(
header.split(",").map((kv) => kv.split("=", 2))
);
const timestamp = Number(parts.t);
const signature = parts.v1;
if (!timestamp || !signature) return false;
const drift = Math.abs(Math.floor(Date.now() / 1000) - timestamp);
if (drift > toleranceSeconds) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(`${timestamp}.${rawBody}`)
.digest("hex");
const a = Buffer.from(expected, "hex");
const b = Buffer.from(signature, "hex");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}

重試#

Tuist 會重試任何回傳非 2xx 狀態、逾時或連線失敗的傳送。排程是固定的:

嘗試次數 發送前等待時間
1 (立即)
2 1 分鐘
3 5 分鐘
4 30 分鐘
5 2 小時
6 8 小時
7 24 小時

第七次嘗試失敗後,該傳送將被永久標記為失敗。由於每次嘗試都使用發送時的時間戳記進行簽名,你的重放保護視窗在重試時仍然適用——你無需擴大它。

檢查傳送記錄#

從 Webhooks 頁面開啟端點以查看其傳送歷史記錄。詳細頁面顯示:

  • 一張摘要卡片,包含目標 URL、遮罩後的簽署密鑰、訂閱的事件以及建立日期。
  • 一張傳送圖表,顯示累計總數和失敗次數,範圍限定於選定的時間視窗。
  • 一個事件表格,你可以依狀態、事件類型或事件 ID 進行篩選。

Webhook 端點詳細頁面,顯示摘要卡片和事件傳送圖表

點擊事件以查看該次嘗試的完整請求和回應——Tuist 發送的確切負載、標頭、上游狀態碼以及回應本體。這與你的伺服器看到的數據相同,這使其成為調試簽章驗證不匹配或上游 5xx 錯誤的最快方法。

Webhook 事件詳細頁面,顯示摘要、請求標頭和本體,以及上游回應

傳送記錄會無限期保留,以便你在調試整合時回溯查看。如果你的下游系統需要持久副本(例如為了合規性),請在傳送到達時將其捕獲到你自己的基礎設施上。

輪替或删除端點#

這兩個操作都位於端點列的三點選單中,以及端點的詳細頁面上:

  • 輪替密鑰 — 產生新的簽署密鑰並僅顯示一次。現有的消費者在更新之前驗證會失敗,因此請將輪替與部署一起規劃。
  • 刪除端點 — 移除端點並停止傳送。已記錄的傳送嘗試會保留,直到標準保留期結束。

安全性注意事項#

  • 端點 URL 必須使用 HTTPS。Tuist 拒絕向明文目的地傳送。
  • Tuist 在每次傳送前解析目標主機名,並拒絕環回、RFC1918、鏈路本地、ULA 和雲端元數據地址(169.254.169.254、fd00::/8…)。這可防止設定錯誤的 Webhook 被用於掃描或攻擊運行 Tuist 伺服器的主機。
  • 端點 URL 和簽署密鑰在靜態時加密。它們作為持有者憑證,不包含在 GDPR/CCPA 數據匯出中。
  • 簽署密鑰僅顯示一次。請將其視為密碼:儲存在你的密鑰管理器中,而非程式碼倉庫內。