跳到正文
通达云视频

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-IDstring事件编号(evt_ 开头)。同一事件的重试保持不变,用它去重。
X-TDC-Timestampstring发送时间,Unix 秒。每次重试都会更新。
X-TDC-Signature-256stringsha256=<hex>,其中 hex = HMAC-SHA256(签名密钥, 时间戳 + "." + 请求体原文)。
Content-Typestringapplication/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_idstring与 X-TDC-Event-ID 相同。
event_typestring事件类型,见上表。
task_id / external_idstring任务编号与你的单号。
status / status_zhstring任务状态,与查询接口一致。
generation_status / audit_status / billing_statusstring生成情况、审核结论、费用状态,用于区分失败的三种情况。
outputobject成功时附带成片信息(video_url 等),与查询接口相同。
errorobject失败时附带 code 与 message_zh。
appeal_id / appeal_status / appeal_ruling_verdictstring申诉相关,仅在申诉后出现。
timestampinteger与 X-TDC-Timestamp 相同。

签名密钥

每个客户有自己的一把 Webhook 签名密钥(whsec_ 开头的随机字符串)。平台给你发的通知只用你的这一把签名,别的客户的密钥验不过你的通知。

  • 在客户控制台的「账号设置」里,找到「Webhook 签名密钥」:页面上只显示打码后的样子(whsec_···· 加最后 4 位)和生成或轮换时间,点「复制签名密钥」取得完整密钥,随时可以再复制。
  • 点「轮换」换一把新密钥,立即生效:之后发出的通知都用新密钥签名;还在重试中的通知,下一次重试也改用新密钥签名(event_id 不变)。同一时刻只有一把密钥有效,平台不会在一条通知里带两个签名。
  • 建议在重试窗口(约 1 小时)内把新密钥换到你的服务端。验签不通过时请返回非 2xx(例如 401),平台才会按上面的间隔重发;返回 2xx 就算送达,不再重发。 轮换后,验签没通过的通知会在下一个重试间隔重发,最长要等一个间隔(最长的一个是 39 分钟),所以送达可能比轮换晚一个重试间隔。
  • 企业账号被停用后仍可查看和复制签名密钥,但不能轮换。
本页的示例请求、示例代码和验签模拟器用的是演示密钥 demo-secret,只用来演示算法,与你的真实密钥无关。

校验签名

  1. 取请求头 X-TDC-Timestamp,与当前时间相差超过 5 分钟的直接拒收(防重放)。
  2. 用你的 Webhook 签名密钥(secret,整串含 whsec_ 前缀,在客户控制台的「账号设置」里复制,只放在你的服务端)计算 HMAC-SHA256(secret, 时间戳 + "." + 请求体原文),转成小写十六进制,前面加上 sha256=。
  3. 与 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. #1首次发送
  2. #2上次失败后 10 秒累计约 10 秒
  3. #3上次失败后 1 分钟累计约 1 分 10 秒
  4. #4上次失败后 5 分钟累计约 6 分 10 秒
  5. #5上次失败后 15 分钟累计约 21 分 10 秒
  6. #6上次失败后 39 分钟累计约 1 小时

建议的接收方式

  • 先验签、再按 event_id 去重,然后尽快返回 2xx,耗时的处理放到后台做。
  • 每次重试都会用新的时间戳、按当时有效的签名密钥重新签名,但 event_id 不变;轮换了签名密钥,下一次重试就用新密钥。
  • 重试用完仍未送达时,请用查询接口或 batch-query 补拉结果,不要只依赖回调。