Webhook 验签故障排查与防重放实现

Webhook 验签失败，不一定是密钥错了，也可能是请求正文被重新序列化，甚至验签程序本身在传输中被改坏。原文从一次 Python 语法错误出发，讨论了 HMAC、时间窗口和代码交付链路的防护。

对写 Node 接口、接支付回调或 GitHub 事件的开发者，这篇值得读。不过，作者提供的代码在结尾被截断，部分安全设计也有前提，距离标题所说的「生产级」还有差距。

验签校验的是原始内容，不是 JSON 表达的意思

作者把 Webhook 校验拆成三件事：用消息认证码 HMAC 检查内容完整性和来源，用时间戳限制请求时效，再用 hmac.compare_digest 比较签名，减少逐字节比较带来的计时侧信道风险。

其中最容易踩坑的是第一件。

两段 JSON 即使解析成相同对象，只要空格、换行或字段顺序不同，参与计算的字节就可能不同。发送方给原始正文签名，接收方却对 JSON.parse 后重新生成的正文验签，结果自然可能不匹配。

验签依赖双方约定的字节序列，不能只检查解析后的业务数据是否相同。

原文因此要求，在 FastAPI、Flask 或 Express 中接入时，先取得原始请求体，再做 JSON 反序列化，并以 request.body() 举例。不过，这是处理原则，各框架的具体 API 和中间件配置仍需分别处理。

作者代码实际接收的是字符串类型的 payload，随后编码成 UTF-8。它适合展示计算过程，却没有展示 HTTP 原始字节如何无损进入这个字段。尤其不能把已经解析过的对象随手转回字符串，作为它的输入。

签名原文采用的是 timestamp.payload 形式：

    # 按 timestamp.payload 的形式构造待签名内容
    signed_payload = f"{input_data.timestamp}.{input_data.payload}"

    computed_mac = hmac.new(
        input_data.secret.encode("utf-8"),
        signed_payload.encode("utf-8"),
        getattr(hashlib, algo)
    )
    expected_hash = computed_mac.hexdigest()

    # 使用恒定时间比较，降低计时侧信道风险
    if not hmac.compare_digest(expected_hash.encode("utf-8"), received_hash.encode("utf-8")):
        return WebhookResult(
            status="error",
            error_code="SIGNATURE_MISMATCH",
            message="HMAC signature verification failed. Potential secret mismatch or payload tampering detected.",
            timestamp_delta=delta
        )

要看清第一行：时间戳也参与了签名，而不是只拿来检查是否过期。但 timestamp.payload 只是这份示例采用的协议，原文没有证明它能直接适配开头列举的 Stripe、GitHub、Slack、Shopify，接入时仍要遵守具体平台的签名规则。

那次回归失败，坏的是源码交付链路

原文最具体的故障发生在部署前的自动回归阶段。程序尚未开始处理请求，就在第 46 行报错：

    if delta > input_data.tolerance_seconds:
                ^
SyntaxError: invalid syntax

原本的 > 被转换成了 HTML 实体 >。浏览器预览可能把实体显示成正常的大于号，但写入文件后，Python 读到的仍是那几个字符，于是无法解析。

作者将根因归到代码经过中间转换层、聊天通知钩子或 Markdown 解析器时发生了转义。不过，原文没有提供完整传输日志，无法确定究竟是哪一环改写了源码。

第二个问题更容易落地处理：部署脚本直接执行文件，没有提前跑语法编译检查。作者建议，在 pre-commit 和 CI 中加入 python3 -m py_compile <target>，并配合 ruff、flake8，让这类错误在进入执行阶段前失败。

这里应区分检查能力。py_compile 能发现示例中的语法错误，不能证明验签协议正确，也不能发现所有「字符变了但代码仍合法」的问题。

作者还建议通过 Git 远程仓库或原始二进制对象存储交付代码，避免让富文本内容承担可执行文件的传输任务。这个取舍合理。更准确的边界是：最终执行的文件应来自可追踪、未经展示层改写的构建产物，网页预览不能代替文件检查。

时间窗口和结构校验，还没有覆盖所有边界

这份实现用 Pydantic 的 BaseModel、Field 描述输入与输出，并通过 ValidationError 表达结构校验失败。输入包括 payload、signature、timestamp、secret，以及默认值为 300 秒的 tolerance_seconds。

它用 int(time.time()) 取当前时间，再计算与请求时间戳的绝对差值。因此，过去太久和超前太多的请求都会被拒绝；恰好等于容忍值时仍会通过时间检查，因为条件使用的是 >。

但时间窗口只能缩短重放机会。同一条合法请求在窗口内再次到达，这段代码仍可能通过验签。原文没有展示事件标识去重、存储记录或业务幂等处理，不能据此认定重放攻击已经被完整解决。

签名头按 algorithm=digest 拆分，例如 sha256=...。格式错误返回 INVALID_SIGNATURE_FORMAT，算法不支持返回 UNSUPPORTED_ALGORITHM，超时返回 TIMESTAMP_EXPIRED，摘要不一致返回 SIGNATURE_MISMATCH。

算法检查也有缺口。代码先检查 hashlib.algorithms_available，再调用 getattr(hashlib, algo)。算法出现在可用集合中，并不能保证存在同名属性，也不能保证适合当前 HMAC 调用。更稳妥的接入方式，是由服务端按平台协议固定允许的算法，避免让请求头自由决定。

CLI 设计则比较清晰：通过 --json-input 接收参数，约定成功退出码为 0，验签失败为 1，缺参或结构错误为 2，并输出 JSON。缺参对应 MISSING_ARGUMENT，结构错误对应 VALIDATION_ERROR。实现还优先使用 orjson，缺失时回退到 json，但没有提供性能对照数据。

问题在于，原文的 main() 在缺参提示字符串处就被截断。完整参数解析、异常处理和退出码执行逻辑无法从所给代码中核验，依赖版本也没有交代。

我的判断

作者抓住了两个实用问题：正文处理会破坏验签输入，展示与传输链路也会破坏程序源码。这两类故障都容易被误判成「签名算法有问题」，把它们分开排查很有价值。

但故障复盘能够支持的结论，主要是源码交付需要语法门禁。它不能直接证明整套 Webhook 方案已经达到生产要求。截断的实现、未限制的算法选择、缺失的窗口内去重，以及原始字节到字符串的接入空白，都需要补齐。

和自行拼装通用验签器相比，按平台协议实现，或评估平台提供的验签 SDK，更容易明确兼容边界；具体是否适合仍要检查其输入要求和错误处理。原文没有给出两种做法的对照测试，也没有攻击测试或负载数据，因此「生产级」应视为作者的定位，不能当成已验证结论。

hmac.compare_digest 和语法门禁是值得采用的具体措施，300 秒则是示例默认值。实际容忍窗口仍需结合发送方协议、时钟偏差和重试行为决定。

能拿来做什么

• 在 Express 等 Node 服务中接入 Webhook 时，先确认中间件如何保留原始请求体，再按平台规则构造待签名内容；不要用重新序列化的业务对象替代收到的正文。
• 如果让 AI 生成 Python 验签脚本，或从网页复制代码进入仓库，应对最终文件运行 python3 -m py_compile <target>，并在 CI 中设置相应检查，避免只验证聊天窗口里的代码展示。
• 把验签失败拆成结构错误、时间偏差和摘要不匹配等类别记录，借鉴原文的错误码设计，让排查先定位失败阶段，再检查密钥和正文。
• 将时间窗口校验与业务幂等分别设计；接入前确认合法事件重复投递时的处理方式，不要把「时间戳没过期」当成「事件没处理过」。