Webhook签名与重放防护（HMAC时间戳与重放窗口）最佳实践

一、基线与风险风险：伪造请求、密钥泄露重放、时钟漂移放大、缓存链路污染。基线：固定算法与头字段、时间戳与窗口校验、nonce唯一性与回收、体内容规范化。

二、签名生成import crypto from 'crypto'

function b64url(input: Buffer): string { return input.toString('base64').replace(/=/g,'').replace(/\+/g,'-').replace(/\//g,'_') }

function signWebhook(body: string, tsSec: number, nonce: string, secret: Buffer): string {

const data = `${tsSec}.${nonce}.${body}`

const mac = crypto.createHmac('sha256', secret).update(data).digest()

return b64url(mac)

}

三、服务端校验与重放窗口type Req = { headers: Record<string, string | undefined>; rawBody: string }

type Res = { status: (n: number) => Res; end: (b?: string) => void }

class NonceStore {

keep = new Set<string>()

add(n: string) { this.keep.add(n) }

has(n: string): boolean { return this.keep.has(n) }

del(n: string) { this.keep.delete(n) }

}

function nowSec(): number { return Math.floor(Date.now()/1000) }

function verifyWebhook(req: Req, res: Res, secret: Buffer, windowSec: number, nonces: NonceStore): boolean {

const sig = req.headers['x-signature'] || ''

const ts = Number(req.headers['x-timestamp'] || '0')

const nonce = req.headers['x-nonce'] || ''

if (!Number.isFinite(ts)) return false

if (Math.abs(nowSec() - ts) > windowSec) return false

if (nonces.has(nonce)) return false

const expect = signWebhook(req.rawBody, ts, nonce, secret)

if (expect !== sig) return false

nonces.add(nonce)

return true

}

四、整合与验收function guardWebhook(req: Req, res: Res, secret: Buffer, store: NonceStore) {

const ok = verifyWebhook(req, res, secret, 300, store)

if (!ok) return res.status(401).end('invalid_signature')

}

头字段：`X-Signature/X-Timestamp/X-Nonce`；窗口≤`300`；`nonce`一次性。签名覆盖顺序为`ts.nonce.body`，体需为规范化字符串；失败时拒绝且记录审计。