"Webhook回调重试与幂等设计实战"

Webhook回调重试与幂等设计实战概述Webhook传递在网络抖动与目标端故障下需具备去重、重试与回退能力，确保事件不丢与不重复处理。幂等键与去重窗口class IdempotencyStore { ttlMs: number map = new Map<string, number>() constructor(ttlMs: number) { this.ttlMs = ttlMs } set(key: string): void { this.map.set(key, Date.now() + this.ttlMs) } seen(key: string): boolean { const exp = this.map.get(key) if (!exp) return false if (Date.now() > exp) { this.map.delete(key); return false } return true } } function buildIdempotencyKey(eventId: string, bodyHash: string): string { return `${eventId}:${bodyHash}` } 指数退避重试async function retryWithBackoff(fn: () => Promise<Response>, maxAttempts: number, baseMs: number): Promise<Response> { let attempt = 0 while (attempt < maxAttempts) { const res = await fn() if (res.ok) return res attempt++ const wait = Math.min(30_000, baseMs * Math.pow(2, attempt)) await new Promise(r => setTimeout(r, wait)) } throw new Error("delivery_failed") } 状态码约定2xx：成功接收并完成处理409：幂等键重复，视为已处理429/503：建议重试，走退避策略4xx其他：不重试并记录失败发送端实现async function deliver(url: string, payload: string, idKey: string, store: IdempotencyStore): Promise<Response> { const bodyHash = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(payload)) const key = buildIdempotencyKey(idKey, Array.from(new Uint8Array(bodyHash)).join("")) const fn = () => fetch(url, { method: "POST", headers: { "Content-Type": "application/json", "X-Idempotency-Key": key }, body: payload }) return await retryWithBackoff(fn, 5, 500) } 接收端实现async function handleWebhook(req: { headers: Record<string, string>; body: string }, store: IdempotencyStore): Promise<{ status: number }> { const key = req.headers["x-idempotency-key"] if (!key) return { status: 400 } if (store.seen(key)) return { status: 409 } store.set(key) const ok = await processEvent(req.body) return { status: ok ? 200 : 503 } } 运维要点对重试次数、窗口命中与失败原因进行指标化与告警幂等键采用事件ID与内容哈希组合以抵御重复与篡改对重复事件保持幂等响应，避免副作用以上机制可在常见平台对接场景中提升Webhook传递的可靠性与安全性。