Webhook 安全校验

为确保回调请求的安全性，强烈建议在生产环境中启用 Webhook HMAC 签名校验，防止伪造请求和重放攻击。

算法说明

Kie AI 使用 HMAC-SHA256 算法生成签名，用于验证 Webhook 回调的完整性和真实性。

签名生成步骤：

拼接待签名字符串：taskId + "." + timestampSeconds

taskId：从请求体中获取的任务ID

timestampSeconds：从 X-Webhook-Timestamp 请求头获取的Unix时间戳（秒级）

使用 HMAC-SHA256 计算签名：

signature = HMAC-SHA256(dataToSign, webhookHmacKey)

Base64 编码：

finalSignature = Base64.encode(signature)

获取 Webhook HMAC Key

您可以在 Kie AI 设置页面生成并查看您的 webhookHmacKey。

webhookHmacKey 用于验证回调请求是否来自 Kie AI 官方服务器。请妥善保管此密钥，切勿泄露或提交到代码仓库。

Webhook Header 说明

当您在设置页面启用 webhookHmacKey 功能后，所有回调请求的 HTTP Header 中将包含以下字段：

`X-Webhook-Timestamp`

类型： Integer

必填：是

描述：回调请求发送时的 Unix 时间戳（秒）。

`X-Webhook-Signature`

类型： String

必填：是

描述：使用 HMAC-SHA256 算法生成的签名，采用 Base64 编码。

签名生成规则：

base64(HMAC-SHA256(taskId + "." + timestamp, webhookHmacKey))

其中：

taskId 为回调 body 中的任务 ID

timestamp 为 X-Webhook-Timestamp 的值

webhookHmacKey 为您在控制台生成的密钥

Webhook 校验流程

请按照以下步骤验证 Webhook 请求的合法性：

读取 Header 字段

从 HTTP Header 中提取 X-Webhook-Timestamp 和 X-Webhook-Signature 两个字段。

生成签名

使用本地保存的 webhookHmacKey，按照以下规则生成 HMAC-SHA256 签名：

从请求 body 中提取 task_id

拼接字符串：taskId + "." + timestamp

使用 HMAC-SHA256 算法和 webhookHmacKey 生成签名

对签名结果进行 Base64 编码

对比签名

将计算出的签名与 X-Webhook-Signature 进行对比。使用常量时间比较算法防止时序攻击。

完整示例代码

以下是在常用编程语言中实现 Webhook 签名校验的完整示例：

Node.js

Python

PHP

Java

示例 Webhook 请求

以下是一个完整的 webhook 请求示例：

算法说明#

获取 Webhook HMAC Key#

Webhook Header 说明#

X-Webhook-Timestamp#

X-Webhook-Signature#

签名生成规则：#

Webhook 校验流程#

完整示例代码#

示例 Webhook 请求#

算法说明

获取 Webhook HMAC Key

Webhook Header 说明

`X-Webhook-Timestamp`

`X-Webhook-Signature`

签名生成规则：

Webhook 校验流程

完整示例代码

示例 Webhook 请求