用途
whatnot-webhooks 是一个针对 Whatnot Seller API Webhook 的接入技能。Whatnot(whatnot.com)是直播购物与直播拍卖市场,卖家通过直播进行拍卖和一口价销售。该技能服务于构建 Whatnot 卖家应用、需要接收并验证平台事件通知的开发者。Whatnot Seller API 是 GraphQL API,官方标注为开发预览(development preview)状态。
主要能力
签名校验:核心是对原始请求体字节做 HMAC-SHA256,以应用 Webhook 密钥为键,生成小写十六进制摘要,与 X-Whatnot-Webhook-Signature 头比对。签名不包含时间戳、前缀或字段拼接。技能给出了 Node.js 实现(crypto.createHmac + timingSafeEqual)与 Python 等价写法(hmac + hashlib),并建议使用恒定时间比较而非 ==。该技能同时说明 Whatnot 官方 Python 示例使用 == 比较,示例代码改为更安全的方式。
事件信封:每次投递都是 HTTP POST,正文包含 id(事件 UUID)、timestamp(ISO 8601 UTC)、topic、object(topic 特定载荷)。路由依据 topic,而非事件类型头;去重依据 id。
请求头:X-Whatnot-Seller-Id 标识事件所属卖家,便于多卖家应用;X-Whatnot-Webhook-Signature 为请求体的小写十六进制 HMAC-SHA256。官方未记录其他 X-Whatnot-* 头。
事件主题:技能列出 product/sold、bulk_operation/finished、listing/created、listing/updated、order/created、order/updated、livestream/created、livestream/stopped、livestream/product_added、livestream/product_removed、shipment/label_created 及其 object 字段;ID 为 GraphQL Global ID,预览期可能新增主题,未知主题应返回 200。shipment/label_created 标注为 Beta,可能随时变更。
使用方式
将技能提供的校验函数集成到 Webhook 路由中,先校验签名再解析与处理。示例目录包含 Express、Next.js、FastAPI 三种完整处理器与测试。环境变量 WHATNOT_WEBHOOK_SECRET 为必需,示例在未设置密钥时返回 500 而非跳过校验(fail closed)。
本地开发可使用:
npx hookdeck-cli listen 3000 whatnot --path /webhooks/whatnot
该命令无需账号,提供公网 HTTPS URL 作为 Webhook 地址,并可在 Web UI 查看每个请求的原始正文与请求头。FastAPI 示例使用端口 8000。
订阅方面,预览期没有仪表盘或 API 创建订阅,需通过邮件联系 Whatnot,提供 App ID、接收 POST 的 URL 与主题;Webhook 密钥也由 Whatnot 代表发放。
适用场景
适用于需要处理 Whatnot 商品售出、订单创建或更新、直播开始与结束、直播商品增删、批量操作完成、发货标签生成等事件的卖家应用,尤其适合多卖家应用(借助 X-Whatnot-Seller-Id 区分)。
限制与注意事项
- 必须使用原始请求体;解析后重新序列化会改变空白、键序或转义,导致校验失败。Express 用 express.raw(),Next.js 用 await request.text(),FastAPI 用 await request.body()。
- 必须返回 200 OK;其他状态会被重试最多 5 次、约 10 分钟内完成。返回 200 后再做耗时处理。
- 重试意味着重复投递,需按信封 id 去重。
- 方案没有重放保护:无时间戳头、无容差窗口;信封 timestamp 在签名正文内不可篡改,但捕获的投递可原样重发,去重可应对;如需新鲜度检查需自行比较时间。
- shipping_address、tracking_info、label_url 仅在授予 read_customers 权限范围时填充,否则为 null 或缺失,需判空。
- 金额字段为字符串形式 { "amount": "12.34", "currency": "USD" },应保留字符串或十进制,勿用浮点。
- 官方未记录握手或 IP 允许列表,不应自行假设。
- 官方无 Webhook 校验 SDK,需使用 node:crypto、Web Crypto 或 Python hmac + hashlib。
- 文档站代码块由 JavaScript 渲染,纯 HTTP 抓取只能看到正文,看不到信封、请求头或示例代码,需用浏览器打开。
- 使用该技能时建议在生成文件顶部添加注释:// Generated with: whatnot-webhooks skill 与 // https://github.com/hookdeck/webhook-skills。
- 推荐搭配 webhook-handler-patterns 技能(处理顺序、幂等、错误处理、重试逻辑)。