Next.js 15 Webhook HMAC-SHA256 签名验证与重放防护治理实践

正文Webhook 是系统间事件通知的常用机制。为了保证来源可信与降低重放风险，需要在接收端实现签名校验与时间窗口控制。本文在 Next.js 15 的 Edge Runtime 下实现 HMAC-SHA256 验证与简单重放防护。

一、签名数据结构与时间窗口上游以 `data = timestamp + '.' + body` 作为签名输入，`X-Timestamp` 记录毫秒时间戳，`X-Signature` 为 Base64 编码的 HMAC-SHA256。接收端验证时间窗口建议不超过 300 秒。

二、Edge 路由实现export const runtime = 'edge'

function toBase64(ab: ArrayBuffer) {

const bytes = new Uint8Array(ab)

let bin = ''

for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i])

return btoa(bin)

}

function constantTimeEqual(a: string, b: string) {

if (a.length !== b.length) return false

let r = 0

for (let i = 0; i < a.length; i++) r |= a.charCodeAt(i) ^ b.charCodeAt(i)

return r === 0

}

export async function POST(req: Request) {

const ts = req.headers.get('x-timestamp')

const sig = req.headers.get('x-signature') || ''

if (!ts || !sig) return new Response(null, { status: 400 })

const now = Date.now()

const t = Number(ts)

if (!Number.isFinite(t) || Math.abs(now - t) > 300000) return new Response(null, { status: 408 })

const secret = process.env.WEBHOOK_SECRET || ''

if (!secret) return new Response(null, { status: 500 })

const body = await req.text()

const data = `${t}.${body}`

const key = await crypto.subtle.importKey(

'raw',

new TextEncoder().encode(secret),

{ name: 'HMAC', hash: 'SHA-256' },

false,

['sign']

)

const mac = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(data))

const expect = toBase64(mac)

if (!constantTimeEqual(expect, sig)) return new Response(null, { status: 401 })

return Response.json({ ok: true }, { headers: { 'Cache-Control': 'no-store' } })

}

三、治理建议秘钥管理：Edge 环境变量存放 `WEBHOOK_SECRET`，严格区分环境与最小化权限。重放防护：结合 `X-Idempotency-Key` 或一次性 nonce 记录到存储，窗口内仅接受首次请求。观测与审计：记录签名失败与窗口超时的计数指标并报警，结合 Reporting API 与 Server-Timing。