开发者

X-GenStudio-Signature 头里**可能有多个** v1 值。secret 轮换的 24 小时宽限期内会有两个 —— 一个用新 secret 签、一个用旧的。请**逐一尝试、任一命中即通过**。只读取单个 v1 的实现会在整个轮换期拒掉每一封投递。

请拒绝 t 与当前时间相差超过 5 分钟的请求。签名的内容是 "{t}.{rawBody}" —— 时间戳在签名之内，改了它签名就对不上。

X-GenStudio-Signature: t=1785000000,v1=<hex>,v1=<hex>
X-GenStudio-Event: generation.succeeded
X-GenStudio-Delivery: <delivery id>
X-GenStudio-Event-Version: 1

POST /api/v1/me/webhook-endpoints/{id}/rotate-secret 会**一次性**返回新 secret。旧 secret 在宽限期内继续有效，好让你从容部署而不丢投递；具体时长在响应里给出。

**宽限期内轮换第二次会让最早那把 secret 立刻失效。**endpoint 只保留一把旧 secret，第二次轮换会把它覆盖掉。请等一次轮换部署完成之后再开始下一次。

webhook URL 必须是 https 且端口为 443。若你自托管在别的端口，请在 443 上用反向代理终结 TLS，或使用 ngrok / Cloudflare Tunnel 这类隧道 —— 两者本就在 443 终结，本地联调无需改动。

轮换 secret 与重新发起归属验证**仅在站内可用**。两者都要求重新输入密码，而 API Key 持有者没有密码上下文。这是 MVP 的一次有意的范围划定，不是端点遗漏。

同一个事件最多投递 9 次，**至少**横跨 31 小时。请照这个跨度设你的去重窗口：同一个 X-GenStudio-Delivery id 在这段时间里可能到达多次。

按 X-GenStudio-Delivery 去重，不要按报文去重。同一事件的每一次重试共用同一个 delivery id，而签名**不同**（每次重试都用新的时间戳重新签）。

回任意 2xx 即算确认。其余情况——**包括响应体回得太慢**——都算这一次投递失败并会重试。用完次数之后这一封被判死，你可以从送达日志里手动重投。