登录开始免费试用
easyCoexistence 官方 API

验证 TikTok Webhook:签名标头及检查方法

TikTok 的 API for Business 会在 Tiktok-Signature 标头中为每次推送签名,格式为 t=<unix seconds>,s=<hex>。其中 s 是以应用密钥为键、对 t 的值、句点和请求正文计算出的 HMAC-SHA256。验证时,请对收到的原始正文重新计算该 HMAC,以恒定时间与 s 比较,并拒绝过期的 t。

easyCoexistence 会检查其应用收到的每个 TikTok 评论事件上的 TikTok 签名,然后将已连接账户的评论事件转发到你的 HTTPS 端点,并在 X-EC-Signature 中用仅属于该账户的密钥签名。

t and s

Tiktok-Signature 的两部分:本次推送的 Unix 时间戳(秒)和 TikTok 为其生成的签名。

5 seconds

TikTok Node 示例中的 acceptableDelay,它会拒绝签名正确但早于该时长的推送。

x-tt-logid

用于记录每次推送唯一 ID 的标头,TikTok 建议接收方记录该 ID 以便排查问题。

BRAND_MENTION

提及 Webhook 的事件类型,其订阅指南指向相同的签名验证方法。

v1

easyCoexistence 的 X-EC-Signature 标头中的签名部分,即 t、句点和原始正文的 HMAC-SHA256。

Tiktok-Signature 标头是什么样的?

由逗号分隔的两部分:t 是该次推送的 Unix 时间戳(秒),s 是签名,长 64 个十六进制字符。TikTok 的页面将标头名写作 TikTok-Signature、Tiktok-Signature 和 tiktok-signature;HTTP 标头名不区分大小写,因此应不分大小写地读取,大多数框架本来就是这样处理的。TikTok 示例推送中的其他标头:

Headers from TikTok's sample delivery
content-type: application/json;charset=UTF-8
user-agent: tiktok-webhook
tiktok-signature: t=1641974633,s=dc023ece112b3a07d809896fd929928a132168d95d2a2e43aab0105fbb291df8
webhook-schema-version: v1.0
x-tt-logid: 202201120803530102451591650189C78

TikTok 对哪些字节签名?

t 的值(作为字符串)、句点,然后是正文。TikTok 指南把最后一部分称为请求正文的字符串化 JSON 副本,其 Node 示例通过对已解析的对象执行 JSON.stringify 来重建该副本。只有当两个序列化程序在空白、键顺序和转义上保持一致时,这种做法才能复现 TikTok 的字节,因此应在任何 JSON 中间件读取之前,对按原样到达的正文进行哈希。

哪个密钥作为签名密钥?

开发者应用的密钥,位于 TikTok 开发者门户的 My Apps、App Detail、Basic Information 下。它就是应用已经作为 secret 发送给 /business/webhook/update/、并作为 client_secret 发送给令牌端点的那个值。同一个密钥为每个授权该应用的账户签名推送,因此接收方无需为每个账户单独配置密钥,访问令牌和应用 ID 也都不参与其中。

如何在 Node.js 中检查?

使用 node:crypto 和原始正文。下面的函数拆分标头,对 t、句点和正文字节重新计算 HMAC,以恒定时间比较结果,然后检查 t 是否过期。它将签名部分的名称作为参数,因此同一段代码也能检查 easyCoexistence 转发的推送,其中该部分名为 v1,密钥为该账户的签名密钥:

Node.js and Express: TikTok's deliveries and easyCoexistence's forwards
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

// Tiktok-Signature reads t=<unix>,s=<hex>; X-EC-Signature reads t=<unix>,v1=<hex>.
function verifySignature(rawBody, header, secret, name, maxAgeSeconds = 300) {
  const parts = {};
  for (const item of String(header ?? "").split(",")) {
    const i = item.indexOf("=");
    if (i > 0) parts[item.slice(0, i).trim()] = item.slice(i + 1).trim();
  }
  const signature = parts[name];
  if (!/^\d+$/.test(parts.t ?? "") || !signature) return false;
  const expected = createHmac("sha256", secret)
    .update(parts.t + ".")
    .update(rawBody) // the bytes exactly as they arrived
    .digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  if (a.length !== b.length || !timingSafeEqual(a, b)) return false;
  return Math.abs(Date.now() / 1000 - Number(parts.t)) <= maxAgeSeconds;
}

const app = express();

// TikTok to your own developer app: the app secret, part s
app.post("/webhooks/tiktok", express.raw({ type: "application/json" }), (req, res) => {
  if (!verifySignature(req.body, req.get("tiktok-signature"), process.env.TIKTOK_APP_SECRET, "s")) {
    console.warn("TikTok signature rejected, x-tt-logid:", req.get("x-tt-logid"));
    return res.sendStatus(401);
  }
  res.sendStatus(200); // acknowledge first: TikTok retries anything but a 200
  enqueue(req.body.toString("utf8")); // its content field is itself a JSON string
});

// easyCoexistence to your endpoint: the account's whsec_ secret, part v1
app.post("/webhooks/easycoexistence", express.raw({ type: "application/json" }), (req, res) => {
  if (!verifySignature(req.body, req.get("x-ec-signature"), process.env.EC_SIGNING_SECRET, "v1")) {
    return res.sendStatus(401);
  }
  res.sendStatus(200);
  enqueue(req.body.toString("utf8")); // platform, account_id, external_id, entry
});

推送的时效多长时,应当拒绝?

TikTok 将截止时间交由接收方决定:其指南指出,应计算本地时钟与 t 之间的差值,并决定是否可以接受。其 Node 示例允许 5 秒,窗口这么窄,偏差几秒的服务器时钟就可能拒绝真正的推送;上面的代码允许 300 秒,这也是 easyCoexistence 要求接收方在自身转发上使用的窗口。应从 t(签名所覆盖的推送时间)开始计算,而不是从正文中的 create_time(标记事件发生的时间)计算。在 TikTok 的示例中,t 比 create_time 晚一秒。

端点应当返回什么?

签名验证通过后立即返回 200,其余工作随后再做,因为 TikTok 会把任何其他状态视为投递失败并重发。对于签名不匹配的情况,TikTok 的示例返回 4xx 状态,并记录 x-tt-logid 标头,该标头可在你向 TikTok 报告问题时用于识别请求。正文中的 client_key 标明开发者应用,因此将它与你自己的应用 ID 比较,是一项低成本的二次检查。

Webhook 端点 URL 如何注册?是否会验证?

通过一次 API 调用完成,TikTok 没有文档记载任何用于先测试 URL 的挑战请求。POST /business/webhook/update/ 接收 app_id、密钥、event_type 以及 HTTPS 的 callback_url:VIDEO 对应发布事件,COMMENT 对应 comment.update,在 Mentions API 上,BRAND_MENTION 对应 brand.mention.event。三者都以相同方式签名,GET /business/webhook/list/ 可查看为某事件类型注册的 URL。来源证明就是每次推送上的签名。

能否检查 easyCoexistence 转发事件上的 Tiktok-Signature?

不能,也无此必要。TikTok 用 easyCoexistence 自有开发者应用的密钥为这些推送签名,该密钥不会交给任何工具或 API。easyCoexistence 在每个事件到达时检查该签名,对验证失败的事件返回 401,忽略 client_key 指向其他应用的正文,然后用该连接账户的签名密钥,在 X-EC-Signature 中为转发给你的内容签名。

easyCoexistence 如何为转发内容签名?

在 X-EC-Signature 标头中,格式为 t=<unix>,v1=<hex>,其中 t 是转发的时间,v1 是对 t、句点和按原样发送的正文计算的十六进制 HMAC-SHA256。密钥是该账户的签名密钥,即 whsec_ 加 32 个字符,须完整使用,包括前缀。在其设置的标头中,easyCoexistence 只设置 Content-Type 和本标头,没有事件标头,因此请从 entry.event 读取事件名称:

A forwarded TikTok comment event, as sent
POST https://hooks.example.com/tiktok/
Content-Type: application/json
X-EC-Signature: t=1793318405,v1=<HMAC_SHA256_HEX>

{"platform":"tiktok","account_id":"<ACCOUNT_ID>","external_id":"<TIKTOK_OPEN_ID>","entry":{"event":"comment.update","create_time":1793318400,"content":{...}}}

v1 = hex(HMAC-SHA256(key = "whsec_<SECRET>", message = "1793318405." + raw body))

签名密钥被替换时会怎样?

新密钥从下一次转发起开始签名。再次调用 set_social_webhook_destination 或 PUT /channels/{id}/webhook 会返回新密钥,并立即让旧密钥失效;每次转发只发送一次,因此在切换期间被服务器拒绝的事件会丢失。在新密钥部署期间,请同时接受两个密钥几分钟。关于频道和帖子的状态事件使用另一个密钥,即在控制台的 Profile、Developers 下找到的那个,它们附带 X-EC-Event 和 X-EC-Delivery 标头,并重试约 33 小时。

常见错误

  • 验证已被框架解析过的正文。JSON 中间件会交出一个对象,重新序列化它可能改变 TikTok 的字节;请在 Webhook 路由上读取原始正文。
  • 对签名失败的推送返回 200。TikTok 一旦看到 200 就会停止发送该事件,因此被错误配置的检查拒绝的真实事件就会丢失;4xx 则会让 TikTok 重试最多 72 小时。
  • 使用 === 比较签名,正如 TikTok 示例所做的那样。恒定时间比较(如 timingSafeEqual)不会泄露伪造签名匹配了多少。
  • 对 easyCoexistence 的密钥进行 Base64 解码,或去掉其 whsec_ 前缀。HMAC 密钥就是整个字符串,须与当初只显示一次时完全一致。
使用 EasyCoexistence 完成这些操作

使用 Claude 或 ChatGPT 中的 set_social_webhook_destination,或用 PUT /channels/{id}/webhook 设置端点。每个连接每月 US$ 9 至 US$ 0.75,连接越多单价越低,首 3 天免费试用。

常见问题

x-tt-logid 在 TikTok Webhook 中是什么?

用于记录每次推送唯一 ID 的标头。TikTok 建议接收方记录它,因为在你向 TikTok 报告问题时,它可用于识别该请求。

TikTok 会为验证新的 Webhook URL 发送挑战请求吗?

对于其 API for Business,TikTok 没有文档记载任何挑战请求。调用 /business/webhook/update/ 即可注册 URL,之后推送会带有 Tiktok-Signature,由你的服务器进行检查。

为什么我的 TikTok Webhook 签名始终不匹配?

请检查输入和密钥:HMAC 必须对原样接收的 t、句点和原始正文计算,使用应用密钥,并且应将结果与 s= 之后的值比较,而不是整个标头。

如何验证 easyCoexistence 转发的 TikTok 事件?

使用 X-EC-Signature 以及设置转发目的地时显示的签名密钥:对 t、句点和原始正文重新计算 HMAC-SHA256,与 v1 比较,并拒绝超过 5 分钟的 t。

继续阅读

两分钟连接您的第一个渠道。

无需等待平台审核。连接 WhatsApp、Instagram、TikTok 或其他渠道,然后让您的 AI 发布、回复或生成报告,看它如何运作。

  • 免费试用 3 天
  • 随时取消
  • 仅使用官方 API
  • 全天候 24/7 监控

验证时间