Node.js Webhook 验签:原始字节与幂等提交

用零依赖服务和十九项 HTTP 用例拆解原始字节验签、时间窗、重复与冲突,并说明数据库提交和恢复边界。

订单回调最危险的故障,往往发生在签名验证通过之后:数据库已经把订单改成已支付,响应却在网络中丢了。发送方看见超时,又发一次。第二次请求的签名仍然正确,时间也没有过期。如果处理器把“验签成功”理解成“可以再执行一次”,重复发货就是一个正常网络故障触发的业务事故。

另一类故障出现在更前面。发送方签的是原始请求体,应用却拿解析后的对象重新序列化,再去计算摘要。开发者看到的字段完全一致,签名就是不一致。为了让接口恢复,有人临时关闭验证,结果把一次数据表示问题变成了一个公开的写入口。

这篇文章把接收流程拆开实现:先保护字节边界,再验证消息来源和时间,最后决定这条业务事实是否已经提交。代码使用 Node.js 内置模块,不依赖框架,便于观察每一步。本文定义的是教学用自有协议,不兼容 Stripe 或任何厂商的签名格式。接第三方服务时应优先使用该服务的官方验签实现,尤其不要照搬本文的请求头名称和摘要拼接规则。

一、先说清楚签名到底承诺了什么

我们的协议规定:请求方法为 POST,路径为 /webhooks/demo,正文是 UTF-8 JSON,最多 65536 字节,不接受压缩。签名输入由十进制秒级时间戳、一个英文句点和未经改动的请求体字节拼接而成。算法固定为 HMAC-SHA256,输出为六十四位小写十六进制字符串。时间戳和签名分别放在 x-demo-timestamp、x-demo-signature 中,事件编号则放在正文的 id 字段里。

这里有两个不同层次。HMAC 证明请求由持有共享密钥的一方生成,且签名覆盖的内容没有被修改;它不证明事件对应的订单存在,不证明订单属于当前商户,也不证明付款金额符合业务要求。代码中的 order.paid 只是演示事件,真正系统必须在身份可信之后继续检查租户、订单状态和合法状态迁移,不能让一个签名有效的任意订单编号直接获得履约权限。

路径和方法没有进入这个教学协议的签名输入,因此密钥必须限定在这个端点使用,不能在多个语义不同的入口间复用。自有协议如果要支持跨端点路由,应明确加入协议版本、目标端点等上下文,并对拼接格式做无歧义定义。真实厂商已经定义好的协议则不能自行添加字段,否则双方无法验签。

共享密钥也有一个经常被忽略的属性:发送方和接收方都能生成合法签名。它适合验证一个双方信任的通信通道,不适合当作可以向第三方证明“只能由对方签发”的不可否认凭据。

二、原始字节不是“内容差不多的 JSON”

下面两段正文解析后可以得到相同的业务数据,但字节长度和摘要都不同。空格、换行、字段顺序、Unicode 转义形式,都可能在解析和重新输出时改变。

{"id":"evt_1","type":"order.paid","orderId":"order_42"}
{ "id": "evt_1", "type": "order.paid", "orderId": "order_42" }

所以正确顺序是:保存 Buffer,验证 Buffer,验证成功后再解码和解析。不是先 JSON.parse,再 JSON.stringify,也不是先把正文作为文本做换行替换。接收端不能靠猜测发送方的序列化习惯还原原文。若协议另行规定了规范化 JSON,那就必须双方严格实现同一套规范化算法;本文没有这个约定。

Stripe 的官方故障排查文档也把原始请求体作为验签输入,并明确提醒框架中间件的执行顺序。这条经验可以迁移到其他平台:先画清请求从反向代理到应用处理器之间经过哪些转换,再决定在哪里保留原始正文。HTTP 分块传输的块边界不是正文的一部分,不需要签进去;正文压缩、网关正文映射、字符编码转换则必须与发送方约定一致。

实现中没有调用 setEncoding,而是收集字节块。即使请求没有 Content-Length,累计大小限制仍然生效。签名通过后使用严格 UTF-8 解码,非法字节会得到错误,而不是被替换字符悄悄修正。拒绝压缩则是主动缩小协议边界,避免“签压缩前还是压缩后”以及解压膨胀问题混入这份最小实现。

三、能直接运行的接收端

保存为 server.mjs。启动时必须提供随机的三十二字节密钥,程序不包含默认生产密钥。下面的 seen 和计数器只用于演示处理顺序,重启就会清空,不能用于真实支付系统。

import http from 'node:http';
import { createHmac, createHash, timingSafeEqual } from 'node:crypto';
import { pathToFileURL } from 'node:url';

export function sign(key, timestamp, body) {
  return createHmac('sha256', key).update(`${timestamp}.`).update(body).digest('hex');
}
export function createApp({ key, now = () => Date.now(), capacity = 10000 }) {
  if (!Buffer.isBuffer(key) || key.length < 32) throw new Error('key needs 32 bytes');
  const seen = new Map();
  let applied = 0;
  const server = http.createServer({ maxHeaderSize: 8192 }, (req, res) => {
    const reply = (status, result) => {
      res.writeHead(status, { 'content-type': 'application/json', connection: 'close' });
      res.end(JSON.stringify({ result }));
    };
    const header = name => {
      const values = req.headersDistinct[name];
      return values?.length === 1 ? values[0] : undefined;
    };
    if (req.url !== '/webhooks/demo') return reply(404, 'not_found');
    if (req.method !== 'POST') return reply(405, 'method_not_allowed');
    if (!/^application\/json(?:;\s*charset=utf-8)?$/i.test(header('content-type') ?? '') ||
        (header('content-encoding') ?? 'identity') !== 'identity') {
      return reply(415, 'unsupported_format');
    }
    const ts = header('x-demo-timestamp');
    const signature = header('x-demo-signature');
    if (!/^[1-9][0-9]{0,11}$/.test(ts ?? '') ||
        !/^[0-9a-f]{64}$/.test(signature ?? '')) return reply(401, 'unauthorized');
    const chunks = [];
    let size = 0, rejected = false;
    req.on('data', chunk => {
      if (rejected) return;
      size += chunk.length;
      if (size > 65536) {
        rejected = true;
        chunks.length = 0;
        reply(413, 'too_large');
      } else chunks.push(chunk);
    });
    req.on('error', () => { if (!res.headersSent) reply(400, 'bad_request'); });
    req.on('end', () => {
      if (rejected) return;
      const body = Buffer.concat(chunks);
      const expected = Buffer.from(sign(key, ts, body), 'hex');
      if (!timingSafeEqual(expected, Buffer.from(signature, 'hex')) ||
          Math.abs(Math.floor(now() / 1000) - Number(ts)) > 300) {
        return reply(401, 'unauthorized');
      }
      let event;
      try {
        event = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(body));
      } catch { return reply(400, 'invalid_json'); }
      if (!event || typeof event !== 'object' || Array.isArray(event) ||
          typeof event.id !== 'string' || !/^[a-zA-Z0-9_-]{1,80}$/.test(event.id) ||
          event.type !== 'order.paid' || typeof event.orderId !== 'string' ||
          !/^[a-zA-Z0-9_-]{1,80}$/.test(event.orderId)) {
        return reply(422, 'invalid_event');
      }
      const fingerprint = createHash('sha256').update(body).digest('hex');
      if (seen.has(event.id)) {
        return reply(seen.get(event.id) === fingerprint ? 200 : 409,
          seen.get(event.id) === fingerprint ? 'duplicate' : 'id_conflict');
      }
      if (seen.size >= capacity) return reply(503, 'capacity_exhausted');
      // Teaching-only synchronous state change. Not a durable transaction.
      seen.set(event.id, fingerprint);
      applied += 1;
      reply(200, 'applied');
    });
  });
  server.headersTimeout = 5000;
  server.requestTimeout = 10000;
  server.setTimeout(10000, socket => socket.destroy());
  return { server, stats: () => ({ applied, remembered: seen.size }) };
}
export function readKey() {
  const hex = process.env.WEBHOOK_SECRET_HEX ?? '';
  if (!/^[0-9a-f]{64}$/.test(hex)) throw new Error('set WEBHOOK_SECRET_HEX to 64 lowercase hex digits');
  return Buffer.from(hex, 'hex');
}
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  createApp({ key: readKey() }).server.listen(8787, '127.0.0.1', () => {
    console.log('Listening on http://127.0.0.1:8787/webhooks/demo');
  });
}

这段代码有几处故意写得保守。首先,安全相关请求头只允许出现一次,避免多值请求头在不同代理或库中产生不同解释。其次,摘要先经过固定格式检查,再转成等长 Buffer。Node.js 的 timingSafeEqual 要求两侧字节长度相等,否则会抛错。它能帮助比较摘要,但不会自动让整个请求处理流程获得恒定时间特性,不能把一个函数名当成整条链路的安全认证。

再次,所有鉴权失败都返回同一种结果,不把“密钥错误”“时间戳过旧”“摘要第几个字符不同”分别告诉调用方。日志同样不应记录密钥、完整签名和完整订单正文。诊断可以保留请求标识、正文长度、错误类别计数及内部关联编号,必要时在受控环境复现原始字节,而不是把生产秘密复制到聊天或日志平台。

最后,检查重复、记录事件和增加计数之间没有异步等待。它只说明单个进程的一次同步回调不会在这几行中被另一个请求回调插入。加上数据库调用以后,这个性质就消失了;开启两个实例以后,两张 Map 也完全不共享。不能因为本机连续点两次只增加一次,就认为线上并发幂等已经做好。

四、发送端必须发送自己签过的那一份 Buffer

保存为 send.mjs,与服务端放在同一目录。这里先生成正文 Buffer,再把同一对象用于摘要和 HTTP 发送。不要在计算摘要后又重新拼一次 JSON,也不要让 HTTP 客户端额外做对象序列化。

import { randomUUID } from 'node:crypto';
import { readKey, sign } from './server.mjs';
const id = process.argv[2] ?? randomUUID();
const body = Buffer.from(JSON.stringify({ id, type: 'order.paid', orderId: 'order_42' }));
const timestamp = String(Math.floor(Date.now() / 1000));
const response = await fetch('http://127.0.0.1:8787/webhooks/demo', {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    'x-demo-timestamp': timestamp,
    'x-demo-signature': sign(readKey(), timestamp, body),
  },
  body,
});
console.log(response.status, await response.text());
if (!response.ok) process.exitCode = 1;

在同一个终端中执行下面的命令。测试完应停止这个本地进程;示例只监听回环地址,不会直接对公网提供服务。

export WEBHOOK_SECRET_HEX="$(node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))")"
node server.mjs &
SERVER_PID=$!
node send.mjs evt_local_1
node send.mjs evt_local_1
kill "$SERVER_PID"

第一次应返回 applied,第二次返回 duplicate。两次发送可以有不同的时间戳和签名,但正文事件编号与字节保持一致。本文把事件编号定义为不可变事件的标识,而不是订单编号:一个订单可能先付款、后退款,每种状态变化应有自己的事件。反过来,同一业务事实也可能被上游用两个事件编号表达,因此生产系统还需要订单状态约束,不能只靠事件去重表防止重复履约。

五、时间窗限制旧消息,事件编号限制重复效果

代码采用对称的三百秒时间窗,过去和未来都检查,并在正文收完之后判断。这样不会让一个刚好在窗口内进入连接、却拖延很久才发完正文的请求继续使用接入时的时间判断。三百秒是本教学协议的取值,不是所有支付平台统一的标准;真实接入应遵守平台说明和时钟误差要求。

时间戳必须包含在签名中。如果只校验正文,然后独立读取一个没有被签名覆盖的时间戳,攻击者就可以给旧正文换上当前时间。时间单位也要写进协议,秒和毫秒混用不能靠接收端“自动猜”。服务器需要可靠的时钟同步,出现大面积时间窗错误时应先查时钟、队列延迟和重试路径,而不是无限放宽容忍时间。

时间窗内的同一条合法请求可以被重放任意多次。时间检查不负责阻止这一点。本文用事件编号查重,正文摘要帮助发现“同一个编号却带来另一份内容”。重复请求仍然必须先验签,不能看见一个已处理编号就跳过身份检查。否则攻击者可以利用去重路径探测数据,或者让未验证输入进入不该进入的业务分支。

这份实现对同一编号采用字节级不可变约定,所以即使只添加一个空格,也会返回冲突。这比某些第三方平台的事件语义更严格。若供应商允许每次投递增加不同的元数据,就不能直接照搬原始正文摘要作为冲突条件,需要针对它保证稳定的业务字段定义指纹,并明确哪些差异允许存在。这个取舍必须写进契约,不能等线上冲突出现后临时忽略全部差异。

容量达到一万条时,新事件返回临时失败,已经记录的重复事件仍能得到成功响应。这里没有做静默淘汰,因为一旦把旧编号扔掉,下次重投就会再次执行。这种“宁可停止接收,也不偷偷失去去重保证”的设计便于暴露问题,但不适合长期运行。真实系统需要可持久化的去重表,保留周期应覆盖自动重试、人工补发与业务追溯,而不只是验签的五分钟。

六、真正的幂等边界在数据库提交处

把 seen.set 换成一次缓存写入仍然不够。假设先标记已处理,再更新订单,进程可能在两步之间退出。重试看见标记便返回成功,但订单从未更新。若先更新订单,再标记已处理,崩溃窗口又会让重试重复执行。两种顺序都不能单独解决问题。

如果业务效果与接收记录位于同一关系数据库,应把接收记录的唯一性约束、订单状态变更和需要发出的后续任务放进同一个事务。去重键通常应包含供应商和账户范围,不能假定不同商户的事件编号永远全局唯一。下面是流程草图,不是已经测试过的数据库脚本。

BEGIN
  INSERT inbox(provider, account_id, event_id, fingerprint)
    -- UNIQUE(provider, account_id, event_id)
    -- 已存在时读取已提交记录,比较允许稳定的指纹
  检查订单归属、当前状态与本次允许的状态迁移
  UPDATE orders ... WHERE status = 'awaiting_payment'
  INSERT outbox(...需要发送的履约任务...)
COMMIT
返回 2xx

唯一键冲突的处理必须结合数据库事务语义设计:另一个事务正在写入时,是等待、冲突还是重试,不能靠应用层“先查再插”来猜。业务更新也要校验受影响行数,避免订单已经退款却被晚到的付款事件改回已支付。供应商不保证顺序时,接收顺序不能成为业务事实顺序。

如果事务已经提交,但响应丢失,第二次投递应读取已提交记录并返回成功。这正是重复请求的正常用途。若数据库提交失败,就不能给出成功响应。若把耗时业务交给队列,成功响应的前提应是事件已经进入可恢复的持久队列或事务性收件箱,而不是已经放进内存数组。先返回成功,再异步写库,会在进程退出时留下无法恢复的丢单窗口。

调用外部发货接口不能靠本地数据库事务自动回滚。常见做法是事务内写出站任务,再由工作进程投递,并给外部系统传递稳定的业务幂等键。工作进程仍可能在外部成功、本地确认前退出,因此外部动作也必须能去重。这里追求的是重复投递下的业务效果可控,而不是宣称整个分布式链路具有魔法般的“只执行一次”。

七、错误响应要服务于恢复,而不只是方便调试

本文的响应策略是自有协议的一部分。鉴权失败返回 401;签名有效但正文无法解析返回 400;结构或事件类型不符合约定返回 422;正文过大返回 413;类型或编码不接受返回 415;编号与正文冲突返回 409;临时容量不足返回 503;已成功接收或确认重复返回 200。

这并不意味着所有供应商都会按同样规则重试。有的平台会重试所有非成功状态,有的平台区分永久错误和临时错误。接入前要核对实际行为。对重复事件返回失败通常会制造更多重复,而对无法持久化的事件返回成功则会切断补救渠道。未知事件类型也不能随意照搬本文的拒绝策略:如果供应商会向同一端点投递更多类型,通常应先验签,再根据订阅契约选择安全忽略并确认,避免无意义的重试风暴。

冲突事件需要单独告警,不能伪装成普通重复。它可能意味着上游编号复用、序列化策略改变、租户去重范围出错,或者本地保存了错误指纹。告警要能关联到受控的原始事件存档,但不要在公开错误信息中暴露订单内容。临时容量错误则需要恢复入口,比如扩大持久队列、修复消费者和重放积压,而不是无限等待重试自行解决。

八、用失败路径检验实现

把下面保存为 test.mjs,执行 node --test test.mjs。测试通过真实的本地 HTTP 连接发送请求,服务端时钟固定,避免边界测试随着运行时刻漂移。

import test from 'node:test';
import assert from 'node:assert/strict';
import { once } from 'node:events';
import { createApp, sign } from './server.mjs';
const key = Buffer.alloc(32, 7); // Local test fixture, never a deployment key.
const now = 1800000000;
const payload = id => JSON.stringify({ id, type: 'order.paid', orderId: 'order_42' });
test('webhook contract', async t => {
  const app = createApp({ key, now: () => now * 1000, capacity: 2 });
  app.server.listen(0, '127.0.0.1');
  await once(app.server, 'listening');
  t.after(() => new Promise(resolve => app.server.close(resolve)));
  const url = `http://127.0.0.1:${app.server.address().port}/webhooks/demo`;
  async function request(body, opts = {}) {
    const timestamp = opts.timestamp ?? String(now);
    const response = await fetch(url, {
      method: opts.method ?? 'POST',
      headers: {
        'content-type': 'application/json',
        'x-demo-timestamp': timestamp,
        'x-demo-signature': opts.signature ?? sign(key, timestamp, body),
        ...opts.headers,
      },
      ...((opts.method === 'GET') ? {} : { body }),
    });
    return [response.status, (await response.json()).result];
  }
  const cases = [
    ['accept', payload('one'), {}, [200, 'applied']],
    ['duplicate', payload('one'), {}, [200, 'duplicate']],
    ['same id, new bytes', payload('one') + ' ', {}, [409, 'id_conflict']],
    ['changed signed bytes', payload('two') + ' ', { signature: sign(key, String(now), payload('two')) }, [401, 'unauthorized']],
    ['bad signature', payload('two'), { signature: '0'.repeat(64) }, [401, 'unauthorized']],
    ['bad hex', payload('two'), { signature: 'x'.repeat(64) }, [401, 'unauthorized']],
    ['old', payload('two'), { timestamp: String(now - 301) }, [401, 'unauthorized']],
    ['future', payload('two'), { timestamp: String(now + 301) }, [401, 'unauthorized']],
    ['bad timestamp', payload('two'), { timestamp: '1e9' }, [401, 'unauthorized']],
    ['bad JSON', '{', {}, [400, 'invalid_json']],
    ['bad UTF8', Buffer.from([0xff]), {}, [400, 'invalid_json']],
    ['bad schema', '{}', {}, [422, 'invalid_event']],
    ['wrong method', '', { method: 'GET' }, [405, 'method_not_allowed']],
    ['wrong media', '{}', { headers: { 'content-type': 'text/plain' } }, [415, 'unsupported_format']],
    ['compressed', '{}', { headers: { 'content-encoding': 'gzip' } }, [415, 'unsupported_format']],
    ['body limit', 'x'.repeat(65537), {}, [413, 'too_large']],
    ['boundary accepted', payload('two'), { timestamp: String(now - 300) }, [200, 'applied']],
    ['capacity', payload('three'), {}, [503, 'capacity_exhausted']],
    ['duplicate still works at capacity', payload('one'), {}, [200, 'duplicate']],
  ];
  for (const [name, body, opts, expected] of cases) {
    await t.test(name, async () => assert.deepEqual(await request(body, opts), expected));
  }
  assert.deepEqual(app.stats(), { applied: 2, remembered: 2 });
});

本文代码在 Node.js v24.22.1 上实际运行,十九个子用例全部通过,测试运行器连同父测试显示二十项通过、零失败。最后还断言业务计数仅为二,确保被拒绝的请求和重复投递没有悄悄增加副作用。测试中的固定密钥只是隔离的测试夹具,不是部署建议。

其中最值得保留的回归用例是修改正文末尾空格:它证明验签覆盖的是原始字节。另一个是时间窗边界,恰好三百秒允许,三百零一秒拒绝。还有容量耗尽后重复事件仍然成功,保证过载时不会把所有历史投递都推回重试队列。只测一个合法请求,覆盖不了这几种容易被后续重构破坏的协议性质。

测试没有覆盖真实反向代理、TLS、慢连接攻击、重复请求头在各网关中的解析差异、跨实例竞争、数据库故障注入、密钥轮换或真实供应商的重试。这些边界不能因为本地测试通过就被标记为已验证。接入生产之前,应该用供应商测试环境穿过真实网关发送请求,检查签名原文是否保持不变;再用可控故障在事务提交前后断开连接,确认事件能恢复且不会重复履约。

九、部署时还缺哪些约束

当前服务限制了正文大小、头部大小和请求时间,但这些限制不等于完整的抗拒绝服务能力。攻击者仍能占据连接、消耗握手和摘要计算资源。公网入口需要连接数上限、合理速率限制、反向代理超时以及可观测的拒绝指标。对同一供应商突发重试要留出恢复空间,不能用一个过低的全局限流值把故障恢复永久卡住。Node.js 的超时设置与代理设置也应一起检查,不要假定任意一种超时都能覆盖所有慢速发送模式。

密钥应按环境和端点隔离,由受控配置注入,不进入仓库、镜像和普通日志。轮换时要约定有限重叠期与密钥标识,旧密钥退出后还要考虑积压投递如何重新签发。自有协议可以要求每次重试使用新的时间戳与签名,但事件编号和业务内容保持不变;接第三方协议则按对方行为处理,不能要求别人遵循你的重试规则。

最终验收应该回答三个具体问题:收到的字节是否确实来自授权发送方,这条业务事实是否已经被提交,给出的成功响应是否对应一个可以恢复的持久结果。原始字节、时间窗、去重记录和数据库事务各自解决不同问题。把它们的责任分清,代码才不会在一次普通重试中从“签名正确”滑向“业务做错”。

核对资料

相关文章

评论

登录后即可参与讨论

暂无评论。