跳至内容

Webhook

Webhook 让你的系统能够在 Tuist 内部发生变化时立即做出响应。每当发生相关事件——例如观察到新的测试用例、预览完成上传或不稳定测试得到修复——Tuist 都会向你订阅了该事件类型的每个端点发送 HTTP POST 请求。请求体是一个 JSON 信封,每次交付都携带一个签名头,你可以使用端点的签名密钥进行验证。

你注册目标 URL,选择想要接收的事件,Tuist 会负责签名、重试和交付审计日志。

接收 Webhook 的步骤#

你可以按照以下步骤开始在应用中接收事件通知:

  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.

后续将支持更多事件类型。如果你需要尚未提供的事件类型,请告知我们,我们会将其添加到目录中。

创建端点#

端点按账户配置。从账户设置中打开Webhook,点击添加端点,并提供:

  • 名称 — 端点在列表中的显示方式。
  • 端点 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 数据导出之外。
  • 签名密钥仅显示一次。请像对待密码一样对待它:将其存储在密钥管理器中,而不是代码仓库中。