如何在不停机的情况下轮换 webhook 密钥？

您的接收方可能在不同时间部署。重叠期让使用旧密钥的接收方和使用新密钥的接收方都能验证同一次投递。

在整个部署过程中持续验证投递，确保攻击者的请求无法触发业务逻辑。

轮换时会发生什么？

Bird 会为您提供一个新的签名密钥。请在 24 小时内部署，此期间 Bird 仍使用旧密钥签名。

为您的端点调用 rotateWebhookSecret。保存其 secret，这是一个以 whsec_ 开头的非空字符串，因为它仅在该响应中返回。

在重叠期内，Bird 使用两个密钥分别签名每次投递。webhook-signature 请求头包含以空格分隔的签名，每个签名以 v1, 开头。

接收方可以使用对应的密钥验证任一签名。请在 24 小时内完成部署，因为旧密钥在该窗口期结束后停止签名。

我的处理程序需要做什么？

您的处理程序必须在任一提供的签名与其信任的密钥匹配时接受投递。

仅检查第一个签名的接收方在切换密钥后可能拒绝有效投递。

Standard Webhooks 规范定义了签名列表，以便接收方在轮换期间逐一尝试。在轮换正式端点之前，先用多个签名测试您的验证器。

在整个变更过程中保持时间戳和去重检查。签名验证涵盖了这些检查。

安全的操作顺序是什么？

保存并部署新密钥。在旧密钥的重叠期结束前确认验证正常。

1. 轮换端点密钥并立即存储返回的值。
2. 在 24 小时的重叠期内将新值部署到每个接收方实例。
3. 通过接收方日志和 Bird 的投递尝试，确认接收方已使用新密钥验证投递。
4. 让旧密钥在重叠期结束后自动过期。

轮换操作没有单独的移除步骤。如果旧密钥已泄露，请在接收方获得新密钥后立即停止信任旧密钥。仅执行轮换而不采取其他措施，会使信任旧密钥的接收方在重叠期内仍面临风险。

如果我立即再次轮换会怎样？

在端点达到五个同时有效的密钥之前，可以继续成功轮换。

从一个密钥开始，在旧密钥过期之前，四次轮换即可填满五个槽位。下一次轮换将失败并返回 WebhookTooManySecrets。因此，循环轮换可能导致您在需要新密钥时无法获取。

等待旧密钥过期后再次轮换。反复轮换并不能免去将新密钥部署到接收方的需要。

变更期间投递失败会怎样？

Bird 会重试失败的投递，因此在重试窗口期内修复验证即可恢复这些投递。

重试计划在时间调整前大约持续 27.5 小时。重试结束后，失败的投递也可以通过重放恢复；失败的 webhook 重试说明了重放窗口。

对无法验证的请求返回错误。返回 2xx 会将投递标记为成功，从而将其排除在失败事件重放之外。