Webhook
Webhook 让你的系统能够在 Tuist 内部发生变化时立即做出响应。每当发生相关事件——例如观察到新的测试用例、预览完成上传或不稳定测试得到修复——Tuist 都会向你订阅了该事件类型的每个端点发送 HTTP POST 请求。请求体是一个 JSON 信封,每次交付都携带一个签名头,你可以使用端点的签名密钥进行验证。
你注册目标 URL,选择想要接收的事件,Tuist 会负责签名、重试和交付审计日志。
接收 Webhook 的步骤#
你可以按照以下步骤开始在应用中接收事件通知:
- 确定你的应用想要接收的事件。
- 在本地服务器上创建 Webhook 端点作为 HTTP 端点(URL)。
- 通过解析负载并返回2xx 状态码来处理来自 Tuist 的请求,以便 Tuist 将交付标记为成功。
- 验证每个请求的签名以证明其来自 Tuist。
- 使用 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. |
后续将支持更多事件类型。如果你需要尚未提供的事件类型,请告知我们,我们会将其添加到目录中。
创建端点#
端点按账户配置。从账户设置中打开Webhook,点击添加端点,并提供:
- 名称 — 端点在列表中的显示方式。
- 端点 URL — 必须使用
https://。 - 要监听的事件 — 选择特定事件,或在组级别使用全选。只有当订阅的事件之一触发时,Tuist 才会向端点发送 POST 请求。

保存时,Tuist 会生成一个新的签名密钥并仅显示一次。请立即将其复制到应用的配置中——你将无法再从仪表板中检索它。如果丢失,请使用端点操作菜单中的轮换密钥来生成新密钥。
负载#
每次交付都是一个单独的 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 计算:
signed_payload = "{timestamp}.{raw_request_body}"
signature = HMAC-SHA256(signing_secret, signed_payload)
header = "t={timestamp},v1={hex(signature)}"
要在你这边进行验证:
- 读取
Tuist-Signature头并将其拆分为t=(时间戳)和v1=(十六进制摘要)部分。 - 如果时间戳与服务器当前时间的差值超过 5 分钟,则拒绝该请求。这限制了重放窗口,但并未完全关闭它——请结合下面的幂等性一起使用。
- 重新计算
HMAC-SHA256(signing_secret, "{timestamp}.{raw_body}")并在恒定时间内将其与摘要进行比较。 - 根据负载
id对交付进行去重(也作为Tuist-Event-Id头显示)。它在重试中保持稳定,因此持久化你已处理的 ID 可以防止捕获的请求在容差窗口内被重放,并保护你在重试时免受双重处理的影响。
签名是根据 Tuist 发送的字节计算的。如果你的 Web 框架在验证之前重新解析并重新序列化 JSON,摘要将不匹配。捕获原始正文(例如 Rack 中的 request.body.read,Express 中的原始 Buffer)并将其传递给验证器。
Node.js 中的参考验证器——将相同的四个步骤(解析头、检查时间戳漂移、重新计算 HMAC、恒定时间比较)翻译为你的接收器所使用的语言:
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 过滤的事件表。

点击一个事件以查看该尝试的完整请求和响应——Tuist 发送的确切负载、头信息、上游状态码和响应正文。这与你的服务器看到的数据相同,这使得它成为调试签名验证不匹配或上游 5xx 错误的最快方法。

交付记录将无限期保留,以便你在调试集成时可以回溯。如果你的下游系统需要持久副本(例如为了合规性),请在交付到达时将其捕获到你自己的基础设施上。
轮换或删除端点#
这两个操作都位于端点行和端点详细页面上的三点菜单中:
- 轮换密钥 — 生成一个新的签名密钥并仅显示一次。现有的消费者在更新之前验证会失败,因此请计划在部署时进行轮换。
- 删除端点 — 删除端点并停止交付。已记录的交付尝试将保留到标准保留窗口过期。
安全说明#
- 端点 URL 必须是 HTTPS。Tuist 拒绝向明文目的地交付。
- Tuist 在每次交付之前解析目标主机名,并拒绝环回、RFC1918、链路本地、ULA 和云元数据地址(
169.254.169.254、fd00::/8、…)。这可以防止配置错误的 Webhook 被用于扫描或攻击运行 Tuist 服务器的主机。 - 端点 URL 和签名密钥在静态时加密。它们作为持有者凭据被排除在 GDPR/CCPA 数据导出之外。
- 签名密钥仅显示一次。请像对待密码一样对待它:将其存储在密钥管理器中,而不是代码仓库中。