驗證 TikTok Webhook:Tiktok-Signature 標頭及其檢查方法
TikTok 的 API for Business 會在每次 Webhook 傳送時,於 Tiktok-Signature 標頭中附上 t=<unix 秒數>,s=<十六進位> 格式的簽名。其中 s 是 t 的值、一個句號及請求內容,以開發者應用程式的密鑰計算出的 HMAC-SHA256。驗證時,請以收到的原始內容重新計算該 HMAC,以恆定時間與 s 比較,並拒絕過時的 t。
easyCoexistence 會在其應用程式收到的每個留言事件上檢查 TikTok 的簽名,然後將已連接帳戶的留言事件轉發至您的 HTTPS 端點,並在 X-EC-Signature 中以僅屬於該帳戶的密鑰簽名。
Tiktok-Signature 的兩個部分:該次傳送的 Unix 時間戳(以秒計)及 TikTok 為其生成的簽名。
TikTok Node.js 範例中的 acceptableDelay,會拒絕簽名正確但早於該值的傳送。
標頭攜帶每次傳送的唯一 ID,TikTok 建議接收方記錄,以便排解問題。
提及 Webhook 的事件類型,其訂閱指南指向相同的簽名驗證方法。
easyCoexistence 的 X-EC-Signature 標頭中的簽名部分,為 t、句號及原始內容的 HMAC-SHA256。
Tiktok-Signature 標頭是什麼樣子?
由逗號分隔的兩個部分:t 為該次傳送的 Unix 時間戳(以秒計),s 為簽名,長度為 64 個十六進位字元。TikTok 的頁面寫作 TikTok-Signature、Tiktok-Signature 及 tiktok-signature;HTTP 標頭名稱不分大小寫,因此應不分大小寫地讀取,大多數框架本來就是如此。TikTok 範例傳送中的其他標頭如下:
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: 202201120803530102451591650189C78TikTok 簽署的是哪些位元組?
t 的值(作為字串)、一個句號,然後是內容。TikTok 的指南把最後一部分稱為請求內容的字串化 JSON 副本,其 Node.js 範例則透過對已解析的物件執行 JSON.stringify 來重建該副本。只有當兩個序列化器在間距、鍵的順序及跳脫方式上一致時,才能重現 TikTok 的位元組,因此應在任何 JSON 中間件讀取之前,依原樣對收到的內容進行雜湊。
哪個密鑰是 HMAC 的金鑰?
開發者應用程式的密鑰,可在 TikTok 開發者入口網站的「我的應用程式」、「應用程式詳情」、「基本資訊」下找到。應用程式已將其以 secret 參數傳送至 /business/webhook/update/,並以 client_secret 傳送至權杖端點。同一個密鑰為每個授權該應用程式的帳戶簽署傳送,因此接收方無需為每個帳戶設定金鑰,存取權杖及應用程式 ID 亦不參與其中。
如何在 Node.js 中檢查?
使用 node:crypto 與原始內容。下方函數會拆分標頭,以 t、句號及內容位元組重新計算 HMAC,以恆定時間比較結果,然後檢查 t 的時效。它以簽名部分的名稱作為參數,因此同一段程式碼也能檢查 easyCoexistence 的轉發,該部分在其中稱為 v1,而金鑰則為帳戶的簽署密鑰:
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.js 範例允許 5 秒,這個範圍過於嚴格,時鐘相差數秒的伺服器可能會拒絕真正的傳送;上述程式碼則允許 300 秒,即 easyCoexistence 要求接收方在其自身轉發中採用的時間範圍。應以 t(即簽名所涵蓋的傳送時間)計算,而非以內容中的 create_time 計算,後者標示事件發生的時間。在 TikTok 的範例中,t 比 create_time 晚一秒。
端點應該回應什麼?
簽名驗證通過後應立即回應 200,其餘工作之後再進行,因為 TikTok 會將任何其他狀態視為傳送失敗並重新傳送。若簽名不符,TikTok 的範例會回應 4xx 狀態,並記錄 x-tt-logid 標頭,該標頭可在您向 TikTok 報告問題時識別該請求。內容中的 client_key 標示開發者應用程式,因此與您自己的應用程式 ID 比對,是一項簡單的第二重檢查。
回呼 URL 如何登記,是否會驗證?
透過一次 API 呼叫完成,TikTok 並未記錄任何會先測試該 URL 的挑戰請求。POST /business/webhook/update/ 需要 app_id、密鑰、event_type,以及 HTTPS 的 callback_url:發布事件用 VIDEO,comment.update 的留言事件用 COMMENT,而在 Mentions API 上,brand.mention.event 則用 BRAND_MENTION。三者的簽署方式相同,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 讀取事件名稱:
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 會返回新的密鑰,並立即停用舊密鑰;且每次轉發只傳送一次,因此切換期間伺服器拒絕的事件會遺失。在新密鑰部署期間,應同時接受新舊兩個密鑰數分鐘。有關頻道及貼文的狀態事件則使用另一個密鑰,即在控制台、個人資料、開發者下找到的密鑰,並附帶 X-EC-Event 及 X-EC-Delivery 標頭抵達,重試期間約為 33 小時。
常見錯誤
- 對框架已解析的內容進行驗證。JSON 中間件會交出一個物件,而再次序列化可能改變 TikTok 的位元組;應在 Webhook 路由上讀取原始內容。
- 對簽名失敗的傳送回應 200。TikTok 一旦看到 200 便會停止傳送該事件,因此因設定錯誤的檢查而被拒絕的真實事件會遺失;回應 4xx 則會讓 TikTok 最多重試 72 小時。
- 以 === 比較簽名,正如 TikTok 的範例所做。恆定時間比較(例如 timingSafeEqual)不會洩露偽造簽名有多少部分相符。
- 對 easyCoexistence 的密鑰進行 Base64 解碼,或去掉其 whsec_ 前綴。HMAC 金鑰是整個字串,須與首次顯示時完全相同。
可透過 Claude 或 ChatGPT 使用 set_social_webhook_destination 設定端點,或使用 PUT /channels/{id}/webhook。每個連接每月 US$ 9 起,連接越多越便宜,最低降至 US$ 0.75,首 3 天免費試用。
常見問題
TikTok Webhook 中的 x-tt-logid 是什麼?
每次傳送唯一 ID 的標頭。TikTok 建議接收方記錄它,因為向 TikTok 報告問題時,它可用來識別該請求。
TikTok 會否為新的 Webhook URL 發出挑戰來驗證?
TikTok 的 API for Business 並無此類挑戰。/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 監察
驗證日期