Webhook 回调

当前 webhook 第一版只推送终态事件：

• task.completed
• task.failed

不会推送什么

当前不会推送：

• 任务刚创建
• running 进度增量
• 中间态心跳

也就是说，任务开始时不会回调，只有任务最终成功或失败时才会回调。

推荐使用方式

建议这样理解 webhook：

• 它负责“通知你任务结束了”
• 它不负责替代任务查询成为唯一状态源

最稳妥的做法是：

1. 接收 webhook
2. 验签
3. 记录通知
4. 如有必要，再调用一次 /v1/tasks/{task_id} 做最终确认

验签

签名规则：

HMAC-SHA256(secret, "{timestamp}.{raw_body}")

请求头：

• X-Yeehoo-Event
• X-Yeehoo-Timestamp
• X-Yeehoo-Signature
• X-Yeehoo-Delivery-ID

重试策略

当前服务端投递策略是：

• 超时：5 秒
• 最大尝试次数：5 次
• 退避：立即、30 秒、2 分钟、10 分钟、1 小时

接收方建议

1. 保留原始 body 做验签
2. 校验时间戳
3. 使用 id 或 X-Yeehoo-Delivery-ID 做幂等
4. 先快速回 2xx，再异步处理内部业务

什么时候应该优先接 webhook

更推荐这些场景尽快接入 webhook：

• 视频任务
• 批量图片生成
• 需要服务端异步编排
• 业务不想长期轮询