创建任务时设置转录 API 回调
提交视频链接、创建分块上传任务，以及单次上传的表单字段都支持webhook_url，但不能与reuse_recent同时使用。接入前先看回调参数说明。
访谈上传、播客归档或批量处理社交视频，都适合用Webhook接收后台任务通知。创建成功后，把转录ID存进自己的任务记录，回调到达时就能找到对应的用户操作。
填写最终的公网HTTPS地址，不要填会跳转的地址。开发环境的localhost不能作为接收地址。下面用文件上传举例，可以拿自己的录音测试同一套通知流程。
curl -X POST "https://api.transcript1.com/v1/transcriptions" \
-H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
-F [email protected] \
-F webhook_url=https://example.com/hooks/transcript1按任务ID和事件类型去重
data是转录对象，不含正文。用data.id和type识别重复投递；完成事件到达后，再通过读取接口获取转录文本。
同一事件可能多次送达。即使应用已经处理成功，只要响应超过10秒，投递仍可能被重试。发布文章、通知用户等操作前，应持久化“转录ID＋事件类型”的去重记录。
验签通过后，先可靠保存事件或放入持久队列，尽快返回2xx，再由后台任务按data.id读取文字。不要让接收请求一直等着后续处理。
收到transcription.failed时检查data.error并更新任务状态。取消任务没有回调，应用应在自己的取消流程中同步状态。
X-Transcript1-Signature: t=<unix seconds>,v1=<hex digest>
{
"type": "transcription.completed",
"created_at": "2026-10-13T09:30:04.000Z",
"data": {
"id": "tr_8fK2Lm0PqRsTuVwXyZaBcD",
"object": "transcription",
"status": "completed",
"transcript_source": "speech_to_text",
"billed_minutes": 4,
"error": null
}
}用原始请求体验证HMAC-SHA256
用团队whsec_密钥，对t、.和原始请求体拼接成的内容计算HMAC-SHA256，再以恒定时间比较签名。时间戳过早或过晚都应拒绝，完整流程见签名校验文档。
先读取未经JSON解析的原始请求体。解析后重新序列化，空格或字段顺序可能变化，签名就对不上。先验证时间戳和签名头、比较等长摘要，校验通过后再解析JSON。
下面只演示摘要计算，假定t和v1已经提取并校验。文档提供完整的Node.js和Python示例，采用5分钟的时间戳容差。
使用完整密钥，包含whsec_前缀。团队密钥轮换后，后续投递立即改用新密钥。
const expected = crypto
.createHmac('sha256', secret)
.update(`${t}.${rawBody}`)
.digest('hex');
const valid = v1.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));上线前，把失败和重复投递也测一遍
分别测试完成、失败和重复事件。确认同一次完成不会发布两次，失败事件也不会走“读取文字并发布”的流程。签名不正确和业务处理出错，要分开测试。
每次投递超时为10秒。先确认接收，再做耗时索引或模型调用；后续失败交给应用自己的持久队列重试，不能把Webhook投递重试当成业务队列。
非2xx响应、连接错误和超时都会触发重试，间隔依次为2、4、8、16、32分钟，最多6次，且不跟随重定向。日志记录任务ID、事件类型和接收状态，不要记录签名密钥。
重试用完后，可用保存的任务ID通过读取转录接口核对状态。创建时就保存ID，别让回调成为任务存在的唯一记录，也不用为查一条漏掉的通知重新提交音视频。