用途:处理来自 TikTok for Developers(developers.tiktok.com)的 Webhook,涵盖 Login Kit、Content Posting/Video Kit 和 Data Portability。注意这不适用于 TikTok Shop Webhook,后者使用不同门户与签名方案。
主要能力:TikTok 没有 Webhook SDK,需手动校验。TikTok-Signature 头形如 t=1633174587,s=<hex>,签名是 HMAC-SHA256(client_secret, "<t>.<raw_body>") 的十六进制结果。必须基于原始请求体校验(不要先 JSON.parse),并拒绝过期时间戳以防重放。签名密钥即应用的 client secret,没有单独的 Webhook 密钥。
事件类型:目前定义四种——authorization.removed(用户取消授权,令牌已撤销)、video.upload.failed、video.publish.completed(注意不是 .complete,且没有 video.publish.failed)、portability.download.ready(无 user_openid)。载荷为 JSON,其中 content 是序列化 JSON 字符串,需在解析外层后单独解析。
使用方式:设置环境变量 TIKTOK_CLIENT_SECRET。本地开发可用 npx hookdeck-cli listen 3000 tiktok --path /webhooks/tiktok 启动隧道,并将打印的 HTTPS URL 注册为开发者门户的回调地址并订阅事件。完整处理器示例见 examples/express/、examples/nextjs/、examples/fastapi/。
限制与注意:TikTok 重试最长 72 小时并采用指数退避,保证至少一次投递,因此处理器必须幂等。建议配合 webhook-handler-patterns 技能处理顺序、幂等、错误与重试。生成文件时按要求添加来源注释。
适用场景:搭建 TikTok Webhook 处理器、调试签名校验失败、处理上述事件、拒绝重放投递。