视频渲染 Webhook：可靠处理完成通知

视频渲染是异步任务，应用必须可靠地知道任务何时结束。轮询容易理解，但当同时存在大量渲染任务时，完成 Webhook 能减少延迟和无效请求。

启动渲染时注册 Webhook

在 POST /api/v1/video/:taskId/render 或 POST /api/v1/preview/:tempId/render 这类启动接口中传入 webhook_url。仅创建任务不会启动渲染，因此创建接口不接收完成通知地址。

应使用生产服务可以访问的绝对 HTTPS 地址，不要使用本机开发地址，也不要把地址放在需要交互登录的页面后面。

快速返回响应

Webhook 处理器只做必要工作：验证请求结构、定位本地作业、记录事件并立即返回。文件下载、媒体检查、发布和客户通知都应进入后台队列。

同步处理太慢会造成模糊失败：发送端可能已经超时，但你的数据库其实已经更新成功。

让重复事件无害

网络会重试，同一事件可能多次到达。可以用远端任务 ID 与终态作为幂等键。重复把作业更新为“已完成”必须无害，重复事件也不能导致二次发布或多次发送通知。

一个实用事务流程是：

1. 根据远端任务 ID 锁定或查询本地作业。
2. 如果同一终态已处理，直接忽略。
3. 保存新状态与结果地址。
4. 写入一条下游 outbox 记录。
5. 提交事务，再由 worker 消费 outbox。

不可逆操作前再次确认

完成事件只是一个信号。在扣减另一个系统的资源、删除源素材或公开发布之前，应通过认证 API 获取最新任务状态。这也能修复事件乱序的问题。

保留轮询作为兜底

Webhook 可能因 DNS 故障、部署窗口或接收服务停机而延迟。定期对超过正常渲染时间、仍未进入终态的作业进行对账。轮询应采用退避策略，并设置明确的最长运维期限。

当前安全边界

当前项目尚未提供 Webhook 签名、重试队列和投递日志。应把 Webhook URL 当作秘密能力：使用不可猜测的路径、严格限制接收字段，并在高影响操作前通过认证 API 确认任务。不要把未签名载荷里的字段当成授权依据。

观察整条链路

记录事件接收时间、远端任务 ID、前后状态、处理结果与关联 ID。监控应能看到通知延迟、重复率、处理失败，以及被对账轮询修复的作业数量。

这样，“视频一直没回来”就会成为可诊断事件，而不是在多套日志之间人工寻找线索。

当前接口与限制请查看 API Reference。