Webhook 签名校验文档

指导代理商验证 EVJ 平台发送的 Webhook 回调请求，确保数据来源可信、内容未被篡改。

1. Webhook 安全机制概述

EVJ 平台每次推送 Webhook 时，都会在 HTTP Header 中携带安全字段：

Header	说明
X-Webhook-Signature	使用 webhook_secret 对 payload 进行 HMAC-SHA256 签名
X-Payload-Sha256	payload 原始内容的 SHA256 指纹
Content-Type	固定为 application/json

代理商必须验证两项内容：

payload 未被篡改

回调确实来源于 EVJ（签名验证）

2. Webhook 请求示例

请求头：

X-Webhook-Signature: 9c0a55be63df...c92a
X-Payload-Sha256: 2cd52a741c49c9...93cd
Content-Type: application/json

请求 Body：

{
  "event": "card.created",
  "card_id": "c_1298123",
  "cardholder_id": 12345,
  "status": "active",
  "timestamp": 1736501235
}

3. 验证步骤

步骤 1：验证 Payload 完整性

计算原始字符串的 SHA256：

local_sha256 = sha256(raw_body)

对比：

local_sha256 == X-Payload-SSha256

步骤 2：验证签名

expected_signature = HMAC_SHA256(raw_body, webhook_secret)

对比：

expected_signature == X-Webhook-Signature

4. 获取 Webhook Secret

通过 API 设置 webhook：

POST /agent/v1/webhook/set

返回示例：

{
  "webhook_url": "https://api.xxx.com/hook",
  "secret": "whsec_ab12cd34ef56..."
}

5. 代码示例

PHP

Node.js（Express）

Python（Flask）

6. 验签失败的常见原因

JSON 被格式化或压缩，导致 SHA256 不一致

代理商中间层修改了 body

使用错误的 webhook_secret

未使用原始 body 进行签名

7. 回调响应要求

返回 200 + 字符串 "ok"：

HTTP/1.1 200 OK
ok

否则平台会自动重试（指数退避）：

次数	延迟
1	立即
2	60s
3	120s
4	180s
5	240s
6	300s
7	360s

8. 安全最佳实践

强制使用 HTTPS

验证签名后再处理业务

不要泄露 webhook_secret

如被泄露，请重新生成

1. Webhook 安全机制概述#

2. Webhook 请求示例#

请求头：#

请求 Body：#

3. 验证步骤#

步骤 1：验证 Payload 完整性#

步骤 2：验证签名#

4. 获取 Webhook Secret#

5. 代码示例#

PHP#

Node.js（Express）#

Python（Flask）#

6. 验签失败的常见原因#

7. 回调响应要求#

8. 安全最佳实践#