Webhook 签名与配置说明 · v1

本文定义 签名算法、安全校验、服务端配置项，并提供 JavaScript / Java / Python 的参考实现代码，直接可跑。
搭配《Webhook 接收消息 “响应体” 格式规范 · v1》一起使用。

一、签名算法（HMAC-SHA256）

平台在回调体中包含字段：Wxid、MessageType、Timestamp、Signature。
你方需要据此进行验签。

拼接明文：{Wxid}:{MessageType}:{Timestamp}（冒号分隔，原样字符串）

算法：HMAC-SHA256

密钥：你在控制台/配置中设置的 secret（共享密钥）

输出：十六进制小写字符串，记为 expectSignature

比较：expectSignature === body.Signature（常量时间比较）

伪代码

bases = Wxid + ":" + MessageType + ":" + Timestamp
expect = HMAC_SHA256_HEX_LOWER(secret, bases)
assert expect == Signature

时间窗口（反重放）

建议对 Timestamp 做时间偏移校验（如允许 ±15 分钟）。

同时对 Data.messages[*].newMsgId 做去重（例如 LRU Set）。

已校验的测试向量

使用 secret = "your-signature-secret"：

Wxid	MessageType	Timestamp	计算明文	期望 Signature
`wxid_xxxxxxxxxxxxxxxx`	`sync_message`	`1757156304`	`wxid_xxxxxxxxxxxxxxxx:sync_message:1757156304`	`df5fdde88d2f3a9329cd0193969c0bac5a1d57e40cc6c28e181f478d3629c510`
`wxid_xxxxxxxxxxxxxxxx`	`sync_message`	`1757156307`	`wxid_xxxxxxxxxxxxxxxx:sync_message:1757156307`	`54cd72f857387f150ae84293ec35fb96e6347e9610ad2f1ee13025e245b72a80`

两个向量均已核对无误，可用于联调自测。

二、服务端配置项（推荐）

支持以 环境变量 或 配置文件 形式注入。

{
  "enabled": true,                 // 是否启用 webhook
  "url": "http://0.0.0.0:8000/webhook", // 你的回调地址（供自检/文档）
  "secret": "your-signature-secret",    // 验签共享密钥
  "includeSelfMessage": true,      // 是否接收自己发出的消息
  "messageTypes": ["*"],           // ["*"] 或具体枚举，如 ["sync_message"]
  "retryCount": 3,                 // 平台端或业务端重试策略参考值
  "timeout": 5,                    // 业务处理超时时间（秒）
  "timestampSkewSec": 900,         // 允许的时间偏移（秒），推荐 900 = 15 分钟
  "dedupeMax": 5000                // 去重缓存容量（按 newMsgId/msgId 组合）
}

生产环境建议：密钥从安全管道（如 KMS / Vault / Secret Manager）注入，不要写死在代码里。

三、接口约定

接收端：POST /webhook（Content-Type: application/json）

健康检查：GET /health

响应：处理成功返回 200/JSON；验签失败返回 401；非法请求返回 400。

示例成功响应：

{ "ok": true, "message": "Webhook received" }

四、代码示例

以下三种语言的实现都包含：验签、时间窗口检查、去重、事件过滤、日志。你可以直接复制粘贴运行。

4.1 JavaScript（Node.js + Express）

依赖：npm i express morgan（Node.js ≥ 18）。

运行：

4.2 Java（Spring Boot）

依赖：spring-boot-starter-web（Maven 或 Gradle 均可）。

Maven 片段：

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-web</artifactId>
</dependency>

代码：

运行：

4.3 Python（Flask）

依赖：pip install flask（可选：pip install gunicorn）。

运行：

五、常见问题（FAQ）

Q1：验签失败怎么办？

确认双方密钥一致、未多空格或换行。

打印实际拼接的明文串进行对照。

用上文测试向量快速自测。

Q2：为何建议保留 rawContent？

便于未知 msgType 的离线补 parser；线上只需先入库防丢。

Q3：如何灰度/压测？

同时配置两条回调 URL（灰度与正式），按比例放量，比较入库差异。

Q4：幂等怎么做？

以 newMsgId|msgId 做幂等键，使用 LRU Set 或持久化 KV（如 Redis）去重。

六、变更日志

v1 (2025-09-07)：首次发布，补充三语言示例与测试向量。

# Webhook 签名与配置说明 · v1

Webhook 签名与配置说明 · v1#

一、签名算法（HMAC-SHA256）#

伪代码#

时间窗口（反重放）#

已校验的测试向量#

二、服务端配置项（推荐）#

三、接口约定#

四、代码示例#

4.1 JavaScript（Node.js + Express）#

4.2 Java（Spring Boot）#

4.3 Python（Flask）#

五、常见问题（FAQ）#

六、变更日志#