SuperAPI AI 工具集

tiktok-shop-webhooks

测试与质量

查看项目

更新于 10-15 22:14

技能介绍

用途:接收并校验 TikTok Shop Webhook,适用于搭建 Webhook 处理器、订阅事件、调试签名校验失败,以及处理 ORDER_STATUS_CHANGE、PACKAGE_UPDATE 等事件。

主要能力:说明 TikTok Shop 的签名校验方式——签名放在 Authorization 头(无 Bearer 前缀),为小写十六进制 HMAC-SHA256;签名消息为 app_key 拼接原始请求体,密钥为 app_secret。校验必须针对原始请求体,不能先 JSON.parse。该机制不属于 Standard Webhooks 规范,也不同于 TikTok Shop 的 API 请求签名;签名中无时间戳,因此无重放保护,需按 tts_notification_id 去重并轮询对账。成功时 3 秒内返回 HTTP 200 空响应体,签名被拒返回 401。

事件与订阅:在 Partner Center 或通过 Events API 按 event_type 字符串订阅,每个主题一个回调 URL。官方提示不要仅依据数字 type 分支,应结合订阅的 event_type 上下文与主题专属 payload schema;官方示例仅出现 type: 1(ORDER_STATUS_CHANGE)。核心 event_type 包括 ORDER_STATUS_CHANGE、RECIPIENT_ADDRESS_UPDATE、PACKAGE_UPDATE、PRODUCT_STATUS_CHANGE、SELLER_DEAUTHORIZATION、UPCOMING_AUTHORIZATION_EXPIRATION 等。

用法:设置环境变量 TIKTOK_SHOP_APP_KEY 与 TIKTOK_SHOP_APP_SECRET。本地开发可用 npx hookdeck-cli listen 3000 tiktok-shop --path /webhooks/tiktok-shop 建立隧道。TikTok Shop 要求 HTTPS 域名端点(不支持 IP 与自定义端口),TLS 1.2+,可在 Partner Center 配置或通过 Events API 管理。

限制:签名无重放保护;投递为至少一次,需幂等去重;TikTok 重试 4 次(2 分钟、30 分钟、3 小时、12 小时)后放弃。建议配合 webhook-handler-patterns 技能处理顺序、幂等、错误与重试。具体价格、平台支持范围等资料暂未提供。