SuperAPI AI 工具集

shipbob-webhooks

智能体与模型

查看项目

更新于 10-16 05:52

技能介绍

用途:该技能面向 ShipBob Webhook 的接收与校验场景,用于搭建处理器、调试签名校验失败,并理解各事件主题(topic)与载荷。

主要能力:ShipBob 采用 Standard Webhooks(与 Svix 相同的字段)签名方案,请求携带 webhook-id、webhook-timestamp、webhook-signature 三个头,事件主题另放在 x-webhook-topic 头(如 order.shipped)。签名为 HMAC-SHA256(secret, "{webhook-id}.{webhook-timestamp}.{body}") 后 base64 编码;签名密钥形如 whsec_<base64>,需去掉 whsec_ 前缀并 base64 解码得到原始 HMAC 密钥。务必对原始未修改的请求体校验(不要先 JSON.parse)。webhook-signature 中是空格分隔的带版本签名(v1,<sig>),应对 v1 条目做时序安全比较。

常见事件主题包括 order.shipped、order.shipment.delivered、order.shipment.tracking.updated、order.shipment.exception、return.created、wro.created、billing.charge.created,分别对应不同读取 scope(如 orders_read/fulfillments_read、returns_read、receiving_read、billing_read)。

使用方式:Node 可通过 standardwebhooks 包校验,Python 无官方 SDK 需按上述算法手写校验;示例代码见 examples/express/、examples/nextjs/、examples/fastapi/。环境变量为 SHIPBOB_WEBHOOK_SECRET=whsec_xxxxx。订阅通过 POST /2026-01/webhook 提交 {"topics": [...], "url": "..."},需 webhooks_write 及各主题对应的 read scope。本地开发可运行 npx hookdeck-cli listen 3000 shipbob --path /webhooks/shipbob。

限制:正文未提供官方 ShipBob SDK;完整主题清单需查阅官方文档;使用该技能生成文件时应按要求添加注释,并建议配合 webhook-handler-patterns 处理幂等与重试(按 webhook-id 去重)。