为确保回调请求的安全性,强烈建议在生产环境中启用 Webhook HMAC 签名校验,防止伪造或篡改的请求。
算法说明#
Emix 使用 HMAC-SHA256 算法对 Webhook 回调签名,用于确认回调确实来自 Emix、且请求体在传输中没有被改动。1.
取原始请求体:Emix 发送的 JSON 请求体的原始字节(UTF-8),不做任何解析。
2.
以 Webhook HMAC Key 为密钥计算 HMAC-SHA256 签名:signature = HMAC-SHA256(rawRequestBody, webhookHmacKey)
3.
finalSignature = Base64.encode(signature)
请对收到的原始请求体直接计算签名。不要先把 JSON 解析再重新序列化后签名:空白或字段顺序的变化都会导致签名不一致。
获取 Webhook HMAC Key#
您可以在 Emix 设置页面(Settings → Webhook HMAC Key)生成并查看您的 webhookHmacKey。重新生成会替换旧密钥,之后发出的回调使用新密钥签名。webhookHmacKey 用于验证回调请求是否来自 Emix 官方服务器。请妥善保管此密钥,切勿泄露或提交到代码仓库。
在设置页面生成 webhookHmacKey 后,所有回调请求的 HTTP Header 中都会包含以下字段。未生成密钥时,回调不带签名头。X-Emix-Signature#
必填: 是(已生成 Webhook HMAC Key 时)
描述: 以 webhookHmacKey 为密钥,对原始请求体计算 HMAC-SHA256 并 Base64 编码后的签名。新接入请校验这个头。
X-Kie-Signature#
必填: 是(已生成 Webhook HMAC Key 时)
描述: 旧头,值与 X-Emix-Signature 完全相同,为兼容保留,已按它校验的接入方不受影响。
签名生成规则:#
base64(HMAC-SHA256(rawRequestBody, webhookHmacKey))
rawRequestBody 为您的服务器收到的原始回调 body(UTF-8 字节)
webhookHmacKey 为您在控制台生成的密钥
Webhook 校验流程#
请按照以下步骤验证 Webhook 请求的合法性:1
读取原始 body 和 Header
在解析 JSON 之前读取原始请求体字节,并从 HTTP Header 中提取
X-Emix-Signature。
2
生成签名
使用本地保存的
webhookHmacKey,对原始请求体计算 HMAC-SHA256,再做 Base64 编码。
3
对比签名
将计算出的签名与
X-Emix-Signature 进行对比。使用常量时间比较算法防止时序攻击。
完整示例代码#
以下是在常用编程语言中实现 Webhook 签名校验的完整示例:示例 Webhook 请求#
注意事项#
请在 10 秒内返回 2xx 状态码。Emix 最多等待 10 秒,回调失败不会重试,错过的结果请用任务详情接口查询。
已按 X-Kie-Signature 校验的,继续可用(值相同);改为校验 X-Emix-Signature 无需其他改动。
密钥泄露时,请在设置页面重新生成并更新您的服务器配置。