接收项目状态通知

添加通知地址

开放后，在设置 → 集成中添加公开的 HTTPS 接收地址，选择事件，并保存只显示一次的签名密钥。也可以使用具有 webhooks:manage 权限的 API Key 创建：

curl --fail-with-body https://api.captionbolt.com/v1/webhooks \
  -H "Authorization: Bearer $CAPTIONBOLT_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"url":"https://receiver.example/captionbolt","events":["project.completed","project.failed"]}'

请替换为实际接收地址。仅支持公开 HTTPS、443 端口，不跟随重定向；localhost 和私有网络地址不能直接接收投递。

选择事件

project.completed：成片导出完成，默认订阅。
project.failed：处理或导出失败，默认订阅。
project.ready：完整处理结束，可以检查或导出。
project.cancelled：项目已取消。

订阅覆盖当前账户通过主站、REST 和 MCP 创建的符合条件的视频项目。独立 Transcripts、已删除和超出访问期限的项目不在范围内。ready 表示处理就绪，不代表用户已经人工检查。

{
  "id": "event-uuid",
  "type": "project.completed",
  "createdAt": "2026-09-10T12:00:00.000Z",
  "data": {
    "projectId": "project-uuid",
    "status": "completed",
    "stage": "export",
    "resultUrl": "https://api.captionbolt.com/v1/projects/project-uuid/result"
  }
}

data.resultUrl 是需要鉴权的 API 地址，不是直接的视频下载链接。请用自己的读取权限 API Key 获取最新下载链接。事件只有元数据，不包含视频或字幕正文。

先验证，再处理

CaptionBolt 遵循 Standard Webhooks。使用兼容的验证库，或在信任事件前完成以下检查：

保留收到的原始请求正文，读取 webhook-id、webhook-timestamp 和 webhook-signature。
从签名密钥移除 whsec_ 前缀，将剩余部分按 base64 解码。对 id.timestamp.rawBody 计算 HMAC-SHA256，以恒定时间比较 base64 签名。
拒绝超出合理时间窗口的过去或未来时间戳，例如五分钟。轮换期间可能出现多个以空格分隔的 v1, 签名，匹配任一可信密钥即可。
按事件 ID 去重，持久化后返回 2xx，再异步执行业务操作。请尽快应答，控制在 15 秒投递时限内。

签名密钥用来验证通知，与 API Key 分开。轮换后新密钥只显示一次，旧密钥有 24 小时过渡期；过渡结束前不能再次轮换。

测试和恢复投递

在设置中发送测试通知，事件类型为 webhook.test，请与项目事件分开处理。查看投递历史、修复接收方错误后，可以手动重试失败或此前已成功的投递。历史记录覆盖最近 30 天。

通知可能重复，也可能乱序。非 2xx、连接失败或应答丢失总共会自动尝试三次：首次投递，以及约 1 分钟、5 分钟后的两次重试；第三次失败后停止自动投递。手动重试沿用原事件 ID，并重新获得完整三次机会，接收方仍需保持幂等。

禁用地址会停止待投递通知，已发出的请求可能仍会完成。删除地址也会删除其投递历史。项目删除或访问过期后，待发送的项目通知会停止。Webhooks 不会延长媒体访问期限，请及时获取和保存结果，也可以按需轮询项目状态。