用途:设置 FastSpring Webhook 处理程序,调试 X-FS-Signature 验证失败问题,处理 order.completed、subscription.activated、subscription.charge.completed 等电商事件,并遍历每次 POST 中批量下发的事件数组。
验证机制:FastSpring 使用你在 webhook 上配置的 HMAC SHA256 Secret,对原始请求体做 HMAC-SHA256、base64 编码后放入 X-FS-Signature 头。必须使用未解析、未重新序列化的原始请求体重新计算,并以恒定时间方式比较。每次 POST 会批量携带多个事件于 events 数组,先对整体 body 验证一次签名,再遍历事件。注意:只有配置了 HMAC secret 才会签名,未配置时不会发送 X-FS-Signature 头。
处理与重试:验证后遍历 payload.events,按 event.type 分发。应以 event.id 去重,因为自动重试复用同一 id(手动重试会生成新 id)。FastSpring 会通过 HTTPS 自动重试,直到端点返回 HTTP 200。常见事件包括 order.completed、order.failed、order.canceled、subscription.activated、subscription.charge.completed、subscription.charge.failed、subscription.updated、subscription.canceled、subscription.deactivated、return.created。
环境变量:FASTSPRING_WEBHOOK_SECRET=your_hmac_sha256_secret,可从 Dashboard → Developer Tools → Webhooks → Configuration 获取。
本地开发:npx hookdeck-cli listen 3000 fastspring --path /webhooks/fastspring,也可选择将 FastSpring 源 IP 107.23.30.83 加入允许列表。
示例与参考:examples/express/、examples/nextjs/、examples/fastapi/ 提供完整处理程序、路由接线、批量遍历、事件分发与测试。references/ 下有 overview.md、setup.md、verification.md。建议配合 webhook-handler-patterns 技能(处理顺序、幂等、错误处理、重试逻辑)及可选的 hookdeck-event-gateway 使用。
限制:资料未提供具体计费方式、价格、支持平台范围或性能指标。