如何使用Webhook 回调?

什么是Webhook?

Webhook 用于在视频生成任务状态变化时，拍我 AI API 平台会自动将结果回调给你。

支持功能列表

目前Webhook 支持功能的列表, 后续会支持更多拍我AI API功能上

功能(端口/接口)	支持情况
`文生视频video/text/generate`	✅
`图生视频video/img/generate`	✅

如何使用

第一步: 创建Webhook_id

访问Webhook管理页面创建webhook_id

第二步: 生成接口加webhook_id字段

第三步:收到Webhook后进行验证,并返回ok

WEB 签名指南

简述

为确保 Webhook 请求的安全性和完整性，所有 Webhook 推送都会携带签名信息。客户端应验证每个请求的签名，以防止请求伪造和数据篡改。

请求格式

HTTP Method

POST

Content-Type

application/json

请求头 (Headers)

Header 名称	类型	说明
`Webhook-Timestamp`	string	Unix 时间戳（秒级）
`Webhook-Nonce`	string	32 位随机字符串，由大小写字母和数字组成
`Webhook-Signature`	string	请求签名（Base64 编码的 HMAC-SHA256）
`Ai-Trace-Id`	string	请求追踪 ID，用于问题排查
`Content-Type`	string	固定值 `application/json`

请求体 (Body)

JSON 格式的业务数据，示例：

{
  "id": "123456789",
  "status": 1,
  "url": "https://example.com/video.mp4",
  "size": 10.5,
  "has_audio": true,
  "credits": 100
}

签名验证算法

步骤 1：构造待签名字符串

待签名字符串由三部分组成，使用换行符 \n 连接：

{timestamp}\n{nonce}\n{url_encoded_payload}

说明：

timestamp：从 Webhook-Timestamp 请求头获取

nonce：从 Webhook-Nonce 请求头获取

url_encoded_payload：将 JSON Body 的各字段按 URL Query String 格式编码

步骤 2：URL 编码 Payload

将 JSON Body 中的每个字段转为 key=value 格式，并使用 & 连接。

示例：

原始 JSON：

{
  "id": "123456789",
  "status": 1,
  "url": "https://example.com/video.mp4",
  "has_audio": true
}

URL 编码后：

has_audio=true&id=123456789&status=1&url=https%3A%2F%2Fexample.com%2Fvideo.mp4

⚠️ 注意：URL Values 编码通常会按 key 的字母顺序排序。

步骤 3：计算签名

使用 HMAC-SHA256 算法，以 Secret Key 为密钥对待签名字符串进行签名，然后进行 Base64 编码。

signature = Base64(HMAC-SHA256(secret_key, sign_string))

步骤 4：比对签名

将计算得到的签名与请求头中的 Webhook-Signature 进行比对。

代码示例

Python

Go

Node.js

Java

响应要求

成功响应

当 Webhook 接收成功时，必须返回：

项目	要求
HTTP Status Code	`200`
Response Body	`ok`（小写，不含引号和其他字符）

示例：

HTTP/1.1 200 OK
Content-Type: text/plain

ok

失败响应

返回非 200 状态码或 Body 不为 ok 时，系统会进行重试。

重试机制

当推送失败时，系统会按以下间隔进行重试：

重试次数	间隔时间
第 1 次	2 秒
第 2 次	10 秒
第 3 次	30 秒
第 4 次	1 分钟
第 5 次	5 分钟
第 6 次	15 分钟
第 7 次	1 小时
第 8 次	4 小时

说明：每次重试间隔会有 ±10% 的随机抖动，以避免重试风暴。达到最大重试次数后，任务将标记为失败。

安全建议

始终验证签名：在处理任何业务逻辑前，务必先验证签名的有效性。

验证时间戳：建议检查 Webhook-Timestamp 是否在合理范围内（如 5 分钟内），以防止重放攻击。

使用 HTTPS：确保 Webhook 接收端点使用 HTTPS 协议。

安全存储密钥：妥善保管 Secret Key，不要将其暴露在客户端代码或版本控制系统中。

使用时间安全的比较函数：使用 hmac.compare_digest（Python）、crypto.timingSafeEqual（Node.js）或 MessageDigest.isEqual（Java）等函数进行签名比对，以防止时序攻击。

幂等处理：由于存在重试机制，同一事件可能被推送多次。建议使用 id 字段进行去重，确保业务逻辑的幂等性。

常见问题

Q: 签名验证失败怎么办？

确认 Secret Key 是否正确

检查 URL 编码实现是否与服务端一致

确认待签名字符串格式正确（注意换行符 \n）

检查布尔值的字符串表示（应为 true/false）

Q: 如何调试签名？

可以打印以下信息进行对比：

原始 payload

URL 编码后的 payload

完整的待签名字符串

计算得到的签名

请求头中的签名

如有其他问题，请联系技术支持。

什么是Webhook?#

支持功能列表#

如何使用#

WEB 签名指南#

简述#

请求格式#

HTTP Method#

Content-Type#

请求头 (Headers)#

请求体 (Body)#

签名验证算法#

步骤 1：构造待签名字符串#

步骤 2：URL 编码 Payload#

步骤 3：计算签名#

步骤 4：比对签名#

代码示例#

Python#

Go#

Node.js#

Java#

响应要求#

成功响应#

失败响应#

重试机制#

安全建议#

常见问题#

Q: 签名验证失败怎么办？#

Q: 如何调试签名？#