用途:在 Editframe 账号中,当渲染完成、文件处理结束等异步事件发生时,接收实时 HTTP 通知。
配置方式:Webhook 绑定在 API 密钥上,而非单独配置。Webhook URL 与订阅事件在创建 API 密钥时设定,可在 Editframe 仪表盘(editframe.com → API Keys → Create)或应用的 API 密钥管理端点完成。仪表盘会返回 webhook secret,需安全保存。
主要能力:事件主题分为渲染事件(render.created、render.pending、render.rendering、render.completed、render.failed)、文件事件(file.created、file.uploading、file.processing、file.ready、file.failed)以及旧版事件 unprocessed_file.created(已弃用)。
安全校验:请求携带 X-Webhook-Signature 头,内容为 HMAC-SHA256 签名。处理前必须校验:用 webhook secret 对原始请求体字符串做 HMAC-SHA256 并转 hex,再用 crypto.timingSafeEqual 比较,避免时序攻击。注意须对原始 body 字符串(如 JSON.stringify(req.body))计算,而非解析后的对象。
使用要点:先快速返回 200 OK,再异步处理事件;根据 topic 与 data 字段执行逻辑。测试可用仪表盘发送测试 webhook,或通过 API 触发测试事件,并可结合 ngrok 做本地调试。
投递保证:HTTP POST 传输 JSON 负载,失败自动指数退避重试 3 次,每次 30 秒超时,重试耗尽后事件标记为失败,并提供投递历史用于调试。
常见问题:签名校验失败通常是未对原始请求体做哈希;超时错误需尽快响应并异步处理;漏收可查看投递日志;重复事件建议基于事件 ID 实现幂等。各主题的具体负载结构与其他细节以对应参考文档为准。