# 用转录 Webhook接收完成或失败通知

> 创建任务时传入webhook_url，即可接收转录 Webhook。转录完成或失败后，transcript1向指定地址发送带签名的POST请求，不必反复轮询。

Canonical: https://transcript1.com/zh/features/zhuanlu-webhook
Language: zh-Hans
Last updated: 2026-10-19

转录 Webhook让后台任务完成后主动通知应用。创建任务时设置webhook_url，转录完成或失败就会收到带签名的POST请求，不必反复查询进度。

- 支持transcription.completed和transcription.failed
- 每次投递都带HMAC-SHA256签名
- 失败后指数退避，最多尝试6次

## 先接收状态通知，再按ID获取转录文本

### 完成和失败各有对应事件

transcription.completed表示转录完成，transcription.failed表示失败。取消转录不会发送Webhook。

### 用团队密钥校验签名

X-Transcript1-Signature包含时间戳和HMAC-SHA256签名，使用团队的whsec_密钥签名原始请求体。

### 收到2xx才算投递成功

其他情况会在2、4、8、16、32分钟后重试，连同首次投递，最多尝试6次。

### 只发送到公网HTTPS地址

回调URL必须使用HTTPS并解析到公网地址，创建任务时和每次投递前都会检查。

### 通知里不塞整份文字

事件包含转录对象，但不含转录正文。拿到ID后，再读取应用需要的文字、JSON或字幕格式。

## 创建任务时设置转录 API 回调

提交视频链接、创建分块上传任务，以及单次上传的表单字段都支持webhook_url，但不能与reuse_recent同时使用。接入前先看[回调参数说明](https://transcript1.com/zh/docs/webhooks#set-a-webhook-url)。

访谈上传、播客归档或批量处理社交视频，都适合用Webhook接收后台任务通知。创建成功后，把转录ID存进自己的任务记录，回调到达时就能找到对应的用户操作。

填写最终的公网HTTPS地址，不要填会跳转的地址。开发环境的localhost不能作为接收地址。下面用文件上传举例，可以拿自己的录音测试同一套通知流程。

### 上传文件并设置Webhook

```
curl -X POST "https://api.transcript1.com/v1/transcriptions" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
  -F file=@episode.mp3 \
  -F webhook_url=https://example.com/hooks/transcript1
```

## 按任务ID和事件类型去重

data是转录对象，不含正文。用data.id和type识别重复投递；完成事件到达后，再通过[读取接口](https://transcript1.com/zh/docs/api-reference#get-a-transcription)获取转录文本。

同一事件可能多次送达。即使应用已经处理成功，只要响应超过10秒，投递仍可能被重试。发布文章、通知用户等操作前，应持久化“转录ID＋事件类型”的去重记录。

验签通过后，先可靠保存事件或放入持久队列，尽快返回2xx，再由后台任务按data.id读取文字。不要让接收请求一直等着后续处理。

收到transcription.failed时检查data.error并更新任务状态。取消任务没有回调，应用应在自己的取消流程中同步状态。

### 发送到回调地址的POST请求

```
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，再以恒定时间比较签名。时间戳过早或过晚都应拒绝，完整流程见[签名校验文档](https://transcript1.com/zh/docs/webhooks#verify-the-signature)。

先读取未经JSON解析的原始请求体。解析后重新序列化，空格或字段顺序可能变化，签名就对不上。先验证时间戳和签名头、比较等长摘要，校验通过后再解析JSON。

下面只演示摘要计算，假定t和v1已经提取并校验。文档提供完整的Node.js和Python示例，采用5分钟的时间戳容差。

使用完整密钥，包含whsec_前缀。团队密钥轮换后，后续投递立即改用新密钥。

### Node.js

```
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));
```

- [查看完整验签示例](https://transcript1.com/zh/docs/webhooks)

## 上线前，把失败和重复投递也测一遍

分别测试完成、失败和重复事件。确认同一次完成不会发布两次，失败事件也不会走“读取文字并发布”的流程。签名不正确和业务处理出错，要分开测试。

每次投递超时为10秒。先确认接收，再做耗时索引或模型调用；后续失败交给应用自己的持久队列重试，不能把Webhook投递重试当成业务队列。

非2xx响应、连接错误和超时都会触发重试，间隔依次为2、4、8、16、32分钟，最多6次，且不跟随重定向。日志记录任务ID、事件类型和接收状态，不要记录签名密钥。

重试用完后，可用保存的任务ID通过[读取转录接口](https://transcript1.com/zh/docs/api-reference#get-a-transcription)核对状态。创建时就保存ID，别让回调成为任务存在的唯一记录，也不用为查一条漏掉的通知重新提交音视频。

## 常见问题

### 在哪里找签名密钥？

在控制台“Webhooks”页面。密钥以whsec_开头，属于当前团队，也可在该页面随时轮换。

### 回调没收到，会自动重试吗？

会。投递失败后按指数退避重试，大约1小时内最多尝试6次。每次超时为10秒，不跟随重定向。

### 通过MCP转录，也能设置Webhook吗？

不能。Webhook仅支持REST API。MCP工具会等待完成，或返回任务ID，供后续读取。

## 相关内容

- [Webhook回调 （文档）](https://transcript1.com/zh/docs/webhooks)
- [音视频文件API](https://transcript1.com/zh/features/yinpin-zhuan-wenzi-api)
- [AI智能体与LLM](https://transcript1.com/zh/use-cases/ai-zhinengti-shipin-zhuanlu)