GloopAPI 接入指南
Webhook 消费
验签、重放与通知配置。
Webhook 通知当前用于普通视频任务结算并进入终态之后；同步图片、语音与持久工作区不能据此假定具有同样订阅能力。通知不包含提示词、结果 URL 或内部诊断信息。
配置与订阅
在账户 Webhooks创建 HTTPS 接收端点并保存一次性签名 secret。管理操作使用登录会话，不是公开 Bearer API；secret 与 API Key 不同。请求视频时传同账户已启用的 webhook_endpoint_id，不接受任意回调 URL。该字段属于幂等输入，重放不能改换端点。
验签与去重
{"id":"evt_example","type":"video.succeeded","created_at":1790000000,"data":{"task_id":"vid_example","status":"succeeded"}}
事件类型为 video.succeeded、video.failed 或 video.cancelled。保存原始请求字节；校验 Webhook-Id、Webhook-Timestamp 和 Webhook-Signature。签名是 v1=<hex>，HMAC-SHA256 使用 secret 字符串作为密钥，消息由 event ID、Unix 秒时间戳和原始 body 用两个换行连接，不附末尾换行：
import hashlib, hmac
message = event_id.encode() + b"\n" + timestamp.encode() + b"\n" + raw_body
expected = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
valid = hmac.compare_digest(received_hex, expected)
限制请求大小，拒绝缺失、重复头和未知签名版本；检查时钟偏差（建议最多 5 分钟），验签成功才解析 JSON，并确认 body 的 id 等于 Webhook-Id。示例只计算签名比较，接收端还需完成上述校验。
先可靠持久化事件或完成幂等处理，再返回 2xx。以稳定 event ID 去重；重试 body 与 ID 不变，时间戳与签名更新。收到事件后用原 Key 查询任务/结果，通知本身不是结果下载凭证。
重试与轮换
网络错误、408、429 和 5xx 自动退避；仅 2xx 算成功，重定向不跟随，其他 4xx 不自动重试。最多 12 次且不超过 24 小时；之后在账户中核查并明确重发。重发只重投通知，不重新生成或收费。
端点更新或密钥轮换增加版本并暂停旧待投递记录，明确重发才使用当前地址与密钥。停用阻止新尝试，不能撤回已发送请求；轮换后同步更新接收方。状态与结算关系见异步任务与幂等。