用途:接收并验证由 Svix 发送的 Webhook,也适用于任何实现 Standard Webhooks 规范的服务商。
主要能力:校验请求头 svix-id、svix-timestamp、svix-signature;处理密钥轮换(同一头部含多个 v1 签名);解析 {"type": "...", "data": {...}} 事件信封。签名内容为 ${svix-id}.${svix-timestamp}.${raw_body},使用 whsec_ 前缀后经 base64 解码的密钥做 HMAC-SHA256,结果再 base64 编码。
使用方式:建议使用官方 svix SDK,它会自动处理 base64 密钥、5 分钟时间戳容差、多签名与常量时间比较。必须传入原始请求体,切勿使用重新序列化的 JSON。Node 示例:const wh = new Webhook(process.env.SVIX_WEBHOOK_SECRET); wh.verify(rawBody, {...})。Python 示例:wh = Webhook(os.environ["SVIX_WEBHOOK_SECRET"]); wh.verify(raw_body, {...})。svix 2.x 起 verify() 返回 undefined/None,校验通过后再自行解析原始请求体。环境变量 SVIX_WEBHOOK_SECRET=whsec_xxxxx,可从发送方仪表盘的 Svix App Portal → Endpoints → Signing Secret 获取。本地开发可用 npx hookdeck-cli listen 3000 svix --path /webhooks/svix。
适用场景:搭建 Express、Next.js、FastAPI 等处理器;调试签名校验失败;处理密钥轮换;接收 Svix 自身的运维 Webhook(如 endpoint.disabled、message.attempt.exhausted)。
限制:Svix 不定义固定事件目录,事件类型由上游发送方决定,需参考发送方文档,并保留默认分支处理未知类型。资料未提供收费、价格等信息。