Go Webhook 验签实战：HMAC、时间窗口和重放防护怎么做

很多系统会通过 Webhook 接收支付、订单、发票、告警等外部事件。最容易出问题的写法，是接口收到 JSON 后直接解析、更新数据库，只靠一个普通 token 或来源 IP 判断是否可信。这样一旦请求被截获、日志泄露或内部转发链路被误用，攻击者就可能重复提交旧请求。

Webhook 验签的重点不是“加一个签名字段”这么简单，而是要把原始 body、时间戳、事件 ID 和 HMAC 绑定在一起。这样才能同时解决三件事：确认请求没有被改、确认请求没有过期、确认同一个事件不会被重复处理。

保护资产：Webhook 接口到底守住什么

Webhook 接口保护的是业务状态，不只是一个 URL。支付成功回调可能修改订单状态，库存回调可能触发发货，告警回调可能创建工单。如果这些请求可以伪造或重放，后果就不是一条日志写错，而是业务状态被重复推进。

先把资产边界列清楚：

• 业务对象：订单、支付单、发票、工单、库存流水。
• 请求内容：原始 body、事件 ID、事件时间、回调类型。
• 共享密钥：只在双方服务端保存，不进入前端和日志。
• 处理结果：是否入库、是否发送消息、是否触发后续任务。

只要一个 Webhook 会修改数据，就应该默认要求验签和去重。

攻击路径：合法请求为什么还能被重放

假设攻击者拿到一条曾经合法的回调请求：

POST /webhook/payment
X-Event-Id: pay_10086
X-Timestamp: 1782809000
X-Signature: 8f3a...

{"order_id":"A1024","status":"paid","amount":199}

如果服务端只校验签名，不校验时间窗口和事件 ID，那么这条旧请求在十分钟、半小时后再次提交，签名仍然可能是对的。签名只能说明“这段内容曾经由可信方生成”，不能自动说明“这次提交仍然有效”。

风险分级：哪些回调必须优先验签

如果项目里 Webhook 很多，可以先按风险分级推进：

• 高风险：支付成功、退款完成、发货、发票开具、权限变更。
• 中风险：任务状态变更、同步成功通知、告警工单。
• 低风险：纯通知类、只写调试日志、不改变业务状态的事件。

高风险回调必须同时满足：签名正确、时间未过期、事件 ID 没处理过、业务状态流转合法。只做其中一项都不够。

防护控制：HMAC、时间窗口和事件去重一起用

下面用标准库写一个核心验签流程。签名内容建议由三部分组成：时间戳、事件 ID、原始 body。三者用固定分隔符拼接后计算 HMAC。

func signPayload(ts string, eventID string, body []byte, secret []byte) string {
    mac := hmac.New(sha256.New, secret)
    mac.Write([]byte(ts))
    mac.Write([]byte("."))
    mac.Write([]byte(eventID))
    mac.Write([]byte("."))
    mac.Write(body)
    return hex.EncodeToString(mac.Sum(nil))
}

校验时不要先把 JSON 解析再重新编码，因为字段顺序、空格和转义都可能变化。必须用请求里的原始 body。

type EventStore interface {
    SeenOrMark(ctx context.Context, eventID string, ttl time.Duration) (bool, error)
}

func verifyWebhook(ctx context.Context, h http.Header, body []byte, secret []byte, store EventStore, now time.Time) error {
    eventID := h.Get("X-Event-Id")
    ts := h.Get("X-Timestamp")
    gotSig := h.Get("X-Signature")
    if eventID == "" || ts == "" || gotSig == "" {
        return fmt.Errorf("missing webhook header")
    }

    sec, err := strconv.ParseInt(ts, 10, 64)
    if err != nil {
        return fmt.Errorf("bad timestamp")
    }
    signedAt := time.Unix(sec, 0)
    if now.Sub(signedAt) > 5*time.Minute || signedAt.Sub(now) > time.Minute {
        return fmt.Errorf("timestamp outside window")
    }

    wantSig := signPayload(ts, eventID, body, secret)
    if !hmac.Equal([]byte(gotSig), []byte(wantSig)) {
        return fmt.Errorf("bad signature")
    }

    seen, err := store.SeenOrMark(ctx, eventID, 10*time.Minute)
    if err != nil {
        return err
    }
    if seen {
        return fmt.Errorf("duplicate event")
    }
    return nil
}

接收接口里要先读取 body，再验签，最后才解析业务 JSON：

func paymentWebhook(secret []byte, store EventStore) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        body, err := io.ReadAll(http.MaxBytesReader(w, r.Body, 1

审计记录：被拒绝的请求也要留下原因

安全接口不能只返回 401，还要让后续排查知道为什么拒绝。建议记录这些字段：

• event_id：事件 ID，没有则记录为空。
• reason：缺头、签名错误、时间过期、重复事件、body 过大。
• remote_ip：请求来源。
• body_hash：body 摘要，不直接写完整 body。

level=warn msg="webhook rejected" event_id=pay_10086 reason="duplicate event" remote_ip=10.0.4.21 body_hash=7b9a...

注意不要把共享密钥、完整签名、完整请求体写进日志。日志是排查工具，不应该变成新的泄露面。

验证清单：用四组请求确认防护有效

最后准备四组最小验证：

• 正确签名 + 当前时间 + 新事件 ID：应该返回 204。
• 篡改 body 后沿用旧签名：应该返回 401。
• 时间戳超过 5 分钟：应该返回 401。
• 同一个事件 ID 重复提交：第一次成功，第二次返回 401。

这四组能覆盖 Webhook 防护最关键的路径。总结一下，HMAC 负责确认内容没被改，时间窗口负责降低旧请求可用性，事件 ID 去重负责阻断重复推进业务状态。三者一起用，才是一个可落地的 Go Webhook 接收方案。