v0 迁移与 Webhook
识别旧 API 的数据形状，校验仍由 v0 提供的状态通知。
新集成应使用 v1。官方仍在迁移窗口保留 v0，v1 Webhook 标记为 coming soon；当前 Webhooks 专题描述的是旧 API 通知，不能直接把 webhook 字段加入 v1 创建请求并假定生效。
迁移时重新建模
v0 把状态和结果直接放在 Agent 上，v1 拆成持久 Agent 与每轮 Run。列表从 agents 形状改为 items；仓库与 Git 结果也不再沿用旧 source/target 对象。按 v1 schema 修改客户端，而不是只替换 URL 版本号。
v0 文档使用 Basic，且写明不支持 MCP；v1 已有 inline mcpServers。v0 artifact 使用 absolutePath，v1 使用列表返回的相对 path。这些能力分别按版本判断。
旧 Webhook 配置
v0 创建请求可提供 webhook，其中 webhook.url 必填，webhook.secret 可选且至少 32 字符。需要验证来源时配置 secret。当前只发送 statusChange，针对 ERROR 或 FINISHED 状态，不是每次中间状态都推送。
| Header | 含义 |
|---|---|
X-Webhook-Signature | sha256=<hex_digest> 格式的 HMAC-SHA256 |
X-Webhook-ID | 该次 delivery 的唯一标识，可用于记录 |
X-Webhook-Event | 当前为 statusChange |
User-Agent | Cursor-Agent-Webhook/1.0 |
校验与接收
使用解析前的原始请求正文计算 HMAC-SHA256，再与签名比较。不能把 JSON 解析后重新序列化的字符串拿来验签，空白或顺序改变也会影响签名。
正文包含 event、timestamp、id、status，可有 source、target 和 summary；可选字段仅在有数据时出现。接收方先验证并保存需要处理的有效负载，再尽快返回 2xx。端点返回错误时可能重试，因此业务处理应考虑重复通知；官方没有在该页承诺具体重试次数或间隔。
生产接收端使用 HTTPS。不要把 User-Agent 或仅有 delivery ID 当作签名认证。新 v1 集成的实时进度目前使用SSE和Run 查询。