Go Webhook 验签如何防重放：HMAC、时间窗与 nonce 去重

支付、订单和仓储系统大多通过 Webhook 接收外部回调事件。有时候一份合法的“支付成功”请求被复制后反复发送，走常规HMAC验签还是能直接通过，业务侧很可能因此重复发货或者给用户重复入账。问题根本不是签名算法出了bug，而是HMAC签名只能证明「请求内容确实来自持有密钥的合作方」，没法证明「这条消息之前从来没被服务端处理过」。

先把 Webhook 的信任边界拆开

一个可审计的Webhook请求通常包含三个核心部分：原始请求正文、发送方携带的时间戳和随机生成的nonce。发送方会把这三部分按提前约定的规则拼接成签名输入串，再用双方共享的密钥生成最终的HMAC值：

timestamp + "." + nonce + "." + rawBody

服务端收到请求之后，要先读取原始正文和对应请求头，检查时间戳是否在允许的范围内，紧接着再自行计算HMAC做比对，确认签名合法之后才把正文交给JSON解码器处理。这个顺序不能乱：如果上来就先把正文解码成结构体，再用 json.Marshal 重新生成新的正文，字段排列顺序、多余空白字符和数字的序列化表示都可能发生变化，导致两份业务含义完全相同的数据，最终算出来的签名完全不一样。

验签必须使用原始请求体

Go写的Webhook handler可以先把请求体读入一个限制了最大大小的字节数组，之后这份字节切片可以同时交给验签和解码两个步骤复用。下面的代码只展示核心边界逻辑，生产环境里密钥一定要从密钥管理系统或者环境变量注入，不要硬编码在代码里：

func verifyWebhook(w http.ResponseWriter, r *http.Request, secret []byte) ([]byte, error) {
    rawBody, err := io.ReadAll(http.MaxBytesReader(w, r.Body, 1

实际项目里还要提前规范签名的编码格式，比如统一用十六进制或者Base64做序列化，同时直接拒绝空的时间戳、空nonce和空签名头。做签名比对的时候要用常量时间比较方法，避免逐字节比对带来的时序泄露风险。

为什么不能把 JSON 结构体拿来签名

不少新手图省事直接把JSON反序列化之后的结构体拿去做签名，这么做相当于把验签协议变成了「本地序列化工具的输出结果」：

var event Event
json.NewDecoder(r.Body).Decode(&event)
again, _ := json.Marshal(event)
// 用 again 计算签名，可能和发送方的 rawBody 不一致

合作方发送请求的时候很可能保留了空字段、用了不一样的小数表示方式，或者JSON字段的排列顺序不一样，最后生成的字节串自然也不一样。签名协议要锁定的是原始字节本身，绝对不能依赖某一个JSON编码器的输出习惯。

时间窗和 nonce 负责挡住重放

签名校验通过之后，服务端还要计算发送方时间和本机时间的偏差，比如常规场景下允许前后偏差5分钟，超出这个窗口的请求直接拒绝即可。时间窗口不是越大越好：窗口设置太大会给被截获的请求留足重放空间，设置太小又容易受服务器时钟漂移影响导致正常请求被误拦。生产环境要统一同步服务器时钟，还要在配置项里明确标注时间单位。

时间窗只能过滤掉很早之前的旧请求，挡不住攻击者在几秒时间窗口内连续重放同一份请求，因此我们还需要把 nonce 写入带自动过期时间的存储组件，用原子操作实现「首次写入成功、重复写入直接失败」的逻辑。对应的伪代码如下：

if abs(time.Now().Unix()-signedAt) > 300 {
    return errors.New("timestamp expired")
}
if !nonceStore.SetNX("webhook:nonce:"+nonce, "1", 10*time.Minute) {
    return errors.New("nonce already used")
}

生成nonce要保证足够随机，同时设置合理的长度上限；空值、过长或者格式明显不符合约定的请求直接拦截。存储写入失败的时候不要悄悄放行，否则重放保护逻辑会在依赖组件故障的时候直接失效。更稳妥的处理方式是临时拒绝请求同时触发告警，或者把请求转到明确标注的降级队列后续人工处理。

验签通过后还要做业务幂等

nonce去重保护的是单次网络传输动作，业务幂等保护的是实际要执行的业务操作。网络重试、发送方重新生成新的nonce、人工补发回调等场景都可能生成新的合法请求，如果这些请求对应的是同一个订单事件，还是要靠数据库唯一键或者业务状态机做最终兜底。

把「已处理事件」的写入操作和业务状态更新放进同一个事务或者同一个可靠流程里，才能避免验签通过之后服务刚好在写库前崩溃，导致发送方后续重试又重复执行对应业务动作。

密钥轮换和日志审计别留到最后

做密钥轮换的时候可以临时支持 key_id：发送方在请求头里标识当前使用的密钥版本，服务端只短期保留旧密钥做过渡适配，同时给旧密钥设置明确的下线时间。不要根据请求自行携带的任意密钥名称直接加载本地文件或者远程配置，密钥ID必须提前映射到服务端维护的白名单列表里。

审计日志可以记录事件ID、nonce的哈希值、时间偏差、签名结果、密钥版本和处理耗时，绝对不要记录共享密钥、完整Authorization头或者回调的完整正文。对连续多次签名失败、同一个nonce重复出现、时间偏差异常的请求来源，可以单独配置对应告警规则。

发布前用五个场景验收

1. 原始正文未被篡改、时间戳在有效期内、nonce从未被使用：返回处理成功，业务逻辑只执行一次。
2. 只修改正文中任意一个字符：签名校验失败，业务表没有新增任何记录。
3. 完全重复发送同一笔请求：nonce去重逻辑命中，不重复执行对应业务动作。
4. 更换一个全新的nonce但复用同一个业务事件ID：验签可以正常通过，但业务幂等逻辑仍会拦截重复扣款或者重复发货操作。
5. 把请求时间戳调整到时间窗口之外，或者临时关闭nonce存储：请求被直接拦截并触发对应告警。

验收脚本最好只保存请求样本的摘要值而不是完整敏感正文，既方便后续做回归测试，也不会把生产环境的敏感凭证提交到代码仓库里。

常见问题

用了 HMAC 还需要 nonce 吗？

需要。HMAC能证明消息完整且由持钥方签出，但没法判断同一条合法消息是不是已经被服务端处理过。时间窗和nonce配合可以最大程度缩小重放攻击的可利用时间范围。

nonce 存 Redis 失败时能不能跳过校验？

不建议。跳过校验就等于在依赖组件故障的时候直接关闭重放防护。更安全的做法是直接拒绝请求并触发告警，让发送方按照提前约定的协议规则重试。

业务事件 ID 和 nonce 可以用同一个值吗？

通常不建议混用。nonce标识的是单次网络传输动作，事件ID标识的是真实发生的一次业务事实，两者的生命周期和幂等语义完全不一样。

总结：验签是入口，幂等才是终点

Go Webhook 的安全边界要从原始请求字节开始搭建，依次经过HMAC校验、时间窗过滤、nonce去重和业务事件幂等四层防护，每一层只解决一个维度的问题，再通过日志和上线前验收把整个流程串起来。这样就算请求被意外重试、恶意复制或者延迟到达，也不会因为「签名校验通过」就自动转换成一次重复的业务动作。