SuperAPI AI 工具集

snipcart-webhooks

前端与建站

查看项目

更新于 10-16 05:52

技能介绍

用途:帮助开发者搭建并调试 Snipcart(snipcart.com,可嵌入 HTML/JS 的购物车)Webhook 处理程序,覆盖接收、校验、事件分发、同步的运费与税费 Webhook,以及本地调试。

校验机制:Snipcart 不对负载做签名,没有签名头、HMAC、共享密钥或时间戳。每个请求带 X-Snipcart-RequestToken 随机令牌,有效期一小时,需用密钥 API Key 以 HTTP Basic(密钥作用户名,末尾冒号,无密码)调用 https://app.snipcart.com/api/requestvalidation/{token} 验证,返回 200 即真实。令牌由攻击者可控,需先用正则 /^[A-Za-z0-9_-]{1,128}$/ 做格式校验再入 URL。密钥缺失时不得放行;网络错误或超时应失败关闭。验证通过后再解析原始 body 分发,并返回状态 200 且 Content-Type 为 application/json。404 表示未知/过期/已校验,401 表示密钥缺失或错误。

事件信封:统一为 eventName、mode、createdOn、content。无事件 ID 和投递 ID,幂等建议以 order token + eventName(+ createdOn)为键;order token 位于 content.token(Order 事件)、content.orderToken(退款/通知/撤回事件)或 content.order.token / content.subscription.id(订阅事件)。常见事件包括 order.completed、order.status.changed、order.paymentStatus.changed、order.trackingNumber.changed、order.refund.created、order.notification.created、order.withdrawal.created,以及 v3/subscription.invoice.payment.succeeded / failed、v3/subscription.state.cancellationRequested / cancelled。v3/ 前缀属于事件名,不可去掉;订阅支付事件仅在续费时触发。负载可能随时新增字段,不应做严格模式校验。

同步 Webhook:shippingrates.fetch 返回 {"rates":[…] },taxes.calculate 返回 {"taxes":[…]},需单独配置,响应体在结账时被消费。

配置与调试:环境变量 SNIPCART_SECRET_API_KEY 需使用商户后台创建的密钥 Key(非公开密钥),且区分 Test 与 Live 模式。本地可用 npx hookdeck-cli listen 3000 snipcart --path /webhooks/snipcart 建立隧道。若由 Hookdeck 的 Snipcart 源完成令牌校验,目标端不应重复校验同一令牌,改为校验 x-hookdeck-signature;shippingrates.fetch 与 taxes.calculate 必须直接指向应用,Hookdeck 无法同步回传目标响应。

限制:资料未提供价格、收费与具体平台支持信息。建议配合 webhook-handler-patterns 技能使用。