Orbit Webhooks

Webhooks push a signed HTTP POST to a URL of your choosing every time a deployment changes state, so your team hears about a failed build in the channel they already watch instead of finding out…

Webhook 会在每次部署状态改变时向您选择的 URL 推送一个签名的 HTTP POST，因此您的团队可以在他们已经在观看的频道中听到构建失败的消息，而不是从客户那里才知道。

Webhook 的位置

打开 Orbit，点击项目，然后在项目标签栏的 Configure 组下选择 Webhooks。该页面标题为 Webhooks，描述为在部署改变状态时接收 HTTP POST 通知，支持 Slack、Discord 和通用 JSON。

Webhooks 和 Hooks 是不同的东西，位于同一菜单中相邻的位置。Webhooks 是传出的：Orbit 告诉您发生了什么。Deploy hooks 是传入的：某些东西告诉 Orbit 进行部署。有关这些，请参阅通过 Deploy Hooks 触发部署。

Orbit 项目的 Webhooks 页面

添加 Webhook

在 Add a webhook 卡中，给它一个 Label。比如它发送到的目的地。
粘贴 URL。它必须以 https:// 开头。
在 Trigger on 下，勾选您想要的事件。
点击 Add webhook。

签名密钥在创建后立即显示一次，并有一个警告，说它不会再被显示。在导航离开前复制它。

一个项目最多可以保存十个 webhook。添加第十一个会被拒绝并显示一条命名该限制的消息。

五个事件

事件	触发时机
Queued	部署进入队列
Building	构建开始
Succeeded	部署已上线
Failed	构建或部署出错
Cancelled	部署在完成前被停止

有意地选择。在一个繁忙的项目上订阅所有五个事件会把一个有用的警报频道变成噪音，让每个人都会将其静音。对于大多数团队，单独的 Failed 是正确的起点，仅在部署通知真正有用的地方（如生产频道）添加 Succeeded。

Slack 和 Discord

如果 URL 是 Slack 传入 webhook 或 Discord webhook，Orbit 会从 URL 检测它并发送格式化消息而不是原始 JSON。该页面在 URL 字段下会说明：Slack 和 Discord URL 是自动检测的。

格式化消息包含项目名称、事件、分支、简短提交、构建时间、部署的 URL 和失败时的错误文本。颜色跟随事件，所以频道中的红卡意味着失败，无需任何人阅读。

不需要其他任何东西。在 Slack 或 Discord 中创建传入 webhook，在此粘贴 URL，选择您的事件，您就完成了。

通用 JSON 有效载荷

任何其他 URL 都会收到一个 JSON 主体。字段为：

字段	内容
`event`	五个事件名称之一，前缀为 `deployment.`
`projectId`，`projectName`，`projectSlug`	哪个项目
`deploymentId`	此次涉及的部署
`gitCommit`，`gitBranch`，`gitCommitMessage`	正在部署的代码
`buildDurationMs`	构建时间，已知时
`deployedUrl`	它上线的位置
`panelUrl`	返回到 KPanel 的链接
`errorMessage`	在失败时出现
`triggeredAt`	ISO 8601 时间戳
`deliveryId`	每次交付唯一，用于去重

使用 deliveryId 来使您的端点具有幂等性。如果您重试交付，或网络故障导致重复，该 id 让您识别您已经处理过它。

验证签名

每次交付都包含三个标头：

X-Orbit-Signature-256，使用您的签名密钥对确切请求主体的 HMAC-SHA256，格式为 sha256= 后跟十六进制摘要。
X-Orbit-Event，事件名称。
X-Orbit-Delivery，交付 id。

在对有效载荷采取行动前验证签名。对原始主体字节计算相同的 HMAC，并使用恒时间比较而不是字符串相等进行比较。

const expected = 'sha256=' + crypto
  .createHmac('sha256', process.env.ORBIT_WEBHOOK_SECRET)
  .update(rawBody)
  .digest('hex');

if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))) {
  return res.status(401).end();
}

对原始请求主体计算 HMAC，在任何 JSON 解析和重新序列化之前。已被解析和字符串化的主体通常是字节不同的，无论您的代码看起来多正确，签名都将永远不匹配。

测试 Webhook

每个 webhook 行都有 Send test delivery。它立即向您的端点发送一个真实交付，并报告它收到的 HTTP 代码或失败详情。

在添加 webhook 后立即使用它，在您依赖它之前。防火墙规则或仅接受 GET 的路由在事件发生期间要容易得多。

交付历史

每行都有过去七天的交付计数、成功百分比和平均持续时间的迷你图表，加上最后触发时间及其结果。

展开 Show delivery history 以查看单个交付：事件、响应代码、持续时间和有错误时的错误文本。任何交付都可以用 Retry delivery 重新发送，它会报告收到的代码。

交付在十二秒后超时。如果您的端点做缓慢的工作，先用 200 确认，然后异步处理，而不是保持连接打开。

轮换密钥

点击 Rotate secret。新密钥显示一次，工具提示明确指出旧密钥立即失效。

这意味着有一个短窗口期间，交付签名使用您的端点不知道的密钥。为此计划：在安静时刻轮换，并将更新您的端点作为下一步操作。

当有权访问密钥的人离开时，或如果它曾被粘贴到共享频道或工单中，应进行轮换。

禁用和删除

Disable webhook 停止交付但保留配置和历史记录，行显示 Disabled 徽章。这是暂停警报的正确选择，例如在计划迁移期间，它会产生大量噪音。

Delete webhook 完全删除它。除非您确定，否则使用禁用。

其他通知方式

Webhook 是灵活的选项。两个更轻量的替代方案位于 Settings 中：

Deploy email notifications，有三个设置：所有部署、仅失败或关闭。
Notification channels，在部署成功或失败时发布到 webhook URL，构建回归和包回归，带有各自的交付历史和测试按钮。

请参阅Orbit 项目设置了解两者。

故障排除

交付显示为失败，并显示 HTTP 代码。 您的端点返回了错误。代码告诉您是哪种：404 表示路径错误，401 或 403 通常表示您自己的签名检查拒绝了它，500 表示您的处理程序抛出错误。

交付失败，超时。 您的端点花费超过十二秒。立即返回 200 并异步完成工作。

完全没有交付。 检查 webhook 是否启用以及您期望的事件是否被勾选。从未进入队列的构建不会触发排队事件。

签名永远无法验证。 几乎总是上面描述的原始主体问题。记录您正在哈希的确切字节并将其长度与 Content-Length 标头进行比较。

Slack URL 被发送为原始 JSON。 Slack 传入 webhook 位于 hooks.slack.com 下。不同的 Slack URL 将不会被检测为 webhook。

接下来去哪里

通过 Deploy Hooks 触发部署用于传入方向。
Orbit 项目设置用于电子邮件通知和通知频道。
Orbit 状态页面告知您的客户，而不仅仅是您的团队。