WEBHOOK
Webhook
创建任务时填了 webhook_url,任务结束(成功、失败或已取消)以及申诉裁决后,平台会向这个地址发送一条带签名的 POST 通知。
事件类型
| event_type | 什么时候发 |
|---|---|
| video.generation.succeeded | 任务成功(含申诉改判通过) |
| video.generation.failed | 任务失败(含申诉裁决后的失败)。下单时就被拦下的请求(例如授权编号无效,返回 422 REAL_PERSON_AUTH_INVALID)直接由创建接口返回错误,不再另发通知。没带授权、或授权范围没覆盖输入素材里的人脸或声音,则下单成功、在预审阶段失败(错误码 PRE_AUDIT_FACE_AUTH_MISSING),会发这个事件 |
| video.generation.canceled | 任务已取消 |
请求格式
| 字段 | 类型 | 说明 |
|---|---|---|
| X-TDC-Event-ID | string | 事件编号(evt_ 开头)。同一事件的重试保持不变,用它去重。 |
| X-TDC-Timestamp | string | 发送时间,Unix 秒。每次重试都会更新。 |
| X-TDC-Signature-256 | string | sha256=<hex>,其中 hex = HMAC-SHA256(签名密钥, 时间戳 + "." + 请求体原文)。 |
| Content-Type | string | application/json; charset=utf-8 |
请求体是紧凑的 JSON(下面为了阅读做了换行)。验签时必须用收到的原文,不要先解析再重新序列化。
POST /hooks/tdc HTTP/1.1
Host: example.com
Content-Type: application/json; charset=utf-8
X-TDC-Event-ID: evt_01JC4R2M7QK8T3V5X7Z9B1D3F5
X-TDC-Timestamp: 1793698272
X-TDC-Signature-256: sha256=464cdff8c82facb8e267864b3873741dcecfcaabcda4a2b14e46d88664b07a97
{
"event_id": "evt_01JC4R2M7QK8T3V5X7Z9B1D3F5",
"event_type": "video.generation.succeeded",
"task_id": "tsk_01JC4QH7Z8M2KX9F3T5V7W2YBD",
"external_id": "ord-20261103-0042",
"status": "SUCCEEDED",
"status_zh": "生成成功",
"generation_status": "COMPLETED",
"audit_status": "POST_AUDIT_PASSED",
"billing_status": "CHARGED",
"output": {
"video_url": "https://download.example.com/videos/tsk_01JC4QH7Z8M2KX9F3T5V7W2YBD.mp4",
"video_url_expires_at": "2026-11-04T09:31:12Z",
"duration_sec": 15,
"resolution": "1376x768",
"has_audio": true
},
"timestamp": 1793698272
}| 字段 | 类型 | 说明 |
|---|---|---|
| event_id | string | 与 X-TDC-Event-ID 相同。 |
| event_type | string | 事件类型,见上表。 |
| task_id / external_id | string | 任务编号与你的单号。 |
| status / status_zh | string | 任务状态,与查询接口一致。 |
| generation_status / audit_status / billing_status | string | 生成情况、审核结论、费用状态,用于区分失败的三种情况。 |
| output | object | 成功时附带成片信息(video_url 等),与查询接口相同。 |
| error | object | 失败时附带 code 与 message_zh。 |
| appeal_id / appeal_status / appeal_ruling_verdict | string | 申诉相关,仅在申诉后出现。 |
| timestamp | integer | 与 X-TDC-Timestamp 相同。 |
签名密钥
每个客户有自己的一把 Webhook 签名密钥(whsec_ 开头的随机字符串)。平台给你发的通知只用你的这一把签名,别的客户的密钥验不过你的通知。
- 在客户控制台的「账号设置」里,找到「Webhook 签名密钥」:页面上只显示打码后的样子(
whsec_····加最后 4 位)和生成或轮换时间,点「复制签名密钥」取得完整密钥,随时可以再复制。 - 点「轮换」换一把新密钥,立即生效:之后发出的通知都用新密钥签名;还在重试中的通知,下一次重试也改用新密钥签名(
event_id不变)。同一时刻只有一把密钥有效,平台不会在一条通知里带两个签名。 - 建议在重试窗口(约 1 小时)内把新密钥换到你的服务端。验签不通过时请返回非 2xx(例如 401),平台才会按上面的间隔重发;返回 2xx 就算送达,不再重发。 轮换后,验签没通过的通知会在下一个重试间隔重发,最长要等一个间隔(最长的一个是 39 分钟),所以送达可能比轮换晚一个重试间隔。
- 企业账号被停用后仍可查看和复制签名密钥,但不能轮换。
本页的示例请求、示例代码和验签模拟器用的是演示密钥
demo-secret,只用来演示算法,与你的真实密钥无关。校验签名
- 取请求头
X-TDC-Timestamp,与当前时间相差超过 5 分钟的直接拒收(防重放)。 - 用你的 Webhook 签名密钥(secret,整串含
whsec_前缀,在客户控制台的「账号设置」里复制,只放在你的服务端)计算HMAC-SHA256(secret, 时间戳 + "." + 请求体原文),转成小写十六进制,前面加上sha256=。 - 与
X-TDC-Signature-256做常量时间比较,一致才处理。
import hashlib
import hmac
import time
def verify_tdc_webhook(secret: str, timestamp: str, raw_body: bytes, signature: str) -> bool:
"""secret:Webhook 签名密钥;raw_body:请求体原文(不要先解析再序列化)"""
# 1. 时间戳必须是 Unix 秒,且与当前时间相差不超过 5 分钟,防重放
try:
ts = int(timestamp)
except (TypeError, ValueError):
return False
if abs(time.time() - ts) > 300:
return False
# 2. HMAC-SHA256(secret, timestamp + "." + body),常量时间比较
mac = hmac.new(secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256)
return hmac.compare_digest("sha256=" + mac.hexdigest(), signature)验签模拟器
下面预填的是上方示例请求(演示密钥 demo-secret,不是你的签名密钥)。直接点「验签」会因为示例时间早已过去而提示超出 5 分钟; 点「用当前时间重新签名」模拟平台重新发送,再看验签通过。改动请求体里任意一个字符,签名就会对不上。
验签模拟器
在浏览器本地计算,签名密钥不会离开本页。请勿粘贴生产环境的签名密钥。
多一个空格、换行或字段顺序变化,签名都会不同。验签必须用收到的原文。
响应与重试
你的服务需要在 10 秒内返回任意 2xx 才算送达;超过 10 秒、返回非 2xx 或连接失败都按失败处理, 按下面的间隔重试,最多共 6 次(首次加 5 次重试,约 1 小时):
- #1首次发送
- #2上次失败后 10 秒累计约 10 秒
- #3上次失败后 1 分钟累计约 1 分 10 秒
- #4上次失败后 5 分钟累计约 6 分 10 秒
- #5上次失败后 15 分钟累计约 21 分 10 秒
- #6上次失败后 39 分钟累计约 1 小时
建议的接收方式
- 先验签、再按 event_id 去重,然后尽快返回 2xx,耗时的处理放到后台做。
- 每次重试都会用新的时间戳、按当时有效的签名密钥重新签名,但 event_id 不变;轮换了签名密钥,下一次重试就用新密钥。
- 重试用完仍未送达时,请用查询接口或
batch-query补拉结果,不要只依赖回调。