TikTok Webhook を検証する:署名ヘッダーと確認方法
TikTok の API for Business は、各 Webhook 配信を Tiktok-Signature ヘッダーで署名します。形式は t=<unix seconds>,s=<hex> で、s は t の値、ドット、リクエストボディを連結したものに対する HMAC-SHA256 です。鍵は開発者アプリのシークレットです。検証するには、受信した生のボディに対して同じ HMAC を再計算し、s と定数時間で比較します。そして古い t は拒否します。
easyCoexistence は、接続済みアカウントのコメントイベントを受け取るたびに TikTok の署名を確認し、そのアカウントのコメントイベントを HTTPS エンドポイントへ転送します。
Tiktok-Signature の 2 つの要素は、その配信の Unix タイムスタンプ(秒)と、TikTok がその配信に対して生成した署名です。
TikTok の Node.js サンプルにある acceptableDelay は、正しく署名されていても、それより古い配信を拒否する値です。
各配信の一意の ID を含むヘッダーです。TikTok は障害調査のために、これを記録するよう受信側に求めています。
メンション Webhook のイベントタイプです。その購読ガイドは、同じ署名検証を参照するよう案内しています。
easyCoexistence の X-EC-Signature ヘッダーの署名部分です。t、ドット、生のボディに対する HMAC-SHA256 です。
Tiktok-Signature ヘッダーはどのような形式ですか?
2 つの要素をカンマで区切ります。t は、その配信の Unix タイムスタンプ(秒)です。s は署名で、16 進数の 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 ミドルウェアが読み込む前に、届いたままのボディをそのままハッシュしてください。
どのシークレットを鍵にしますか?
開発者アプリのシークレットです。TikTok の開発者ポータルで「My Apps」「App Detail」「Basic Information」の順にたどると見つかります。このアプリは、/business/webhook/update/ へは secret として、トークンエンドポイントへは client_secret として、すでにこの値を送信しています。1 つのシークレットが、アプリを認可した各アカウントの配信すべてに署名します。そのため受信側はアカウントごとの鍵を必要とせず、アクセストークンもアプリ 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 の差を計算して、許容できるかどうかを判断します。TikTok の Node.js サンプルは 5 秒を許容します。これは、数秒ずれたサーバーのクロックが正当な配信を拒否しかねないほど厳しい値です。上のコードは 300 秒を許容します。これは easyCoexistence が自身の転送について、受信側に使うよう求めている時間枠です。測定の基準は、署名が対象とする配信時刻である t です。ボディ内の create_time は基準にしません。create_time はイベントが発生した時刻を示します。TikTok のサンプルでは、t は create_time の 1 秒後です。
エンドポイントは何を返すべきですか?
署名が一致したら直ちに 200 を返し、処理は後で行ってください。TikTok はそれ以外のステータスを配信失敗とみなして再送するためです。署名が一致しない場合、TikTok のサンプルは 4xx ステータスを返し、x-tt-logid ヘッダーを記録します。このヘッダーは、TikTok に問題を報告する際にそのリクエストを特定するためのものです。ボディの client_key は開発者アプリを示すため、自分のアプリ ID と比較すると、手軽な 2 つ目の確認になります。
コールバック URL はどのように登録し、検証されますか?
API の 1 回の呼び出しで登録します。TikTok は、URL を先にテストするチャレンジリクエストを文書化していません。POST /business/webhook/update/ は app_id、secret、event_type、HTTPS の callback_url を受け取ります。event_type は、投稿イベントには VIDEO、comment.update には COMMENT を指定します。Mentions API の場合は、brand.mention.event に BRAND_MENTION を指定します。3 つすべて同じ方法で署名されて届きます。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 の 16 進数です。鍵はアカウントの署名シークレットで、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 を呼び出すと新しいシークレットが返され、古いものはただちに無効になります。各転送は 1 回だけ送られるため、切り替え中にサーバーが拒否したイベントは失われます。新しいシークレットのデプロイ中は、数分間は両方のシークレットを受け入れてください。チャネルと投稿に関するステータスイベントは別のシークレットを使います。それはダッシュボードの「Profile」「Developers」にあるシークレットです。X-EC-Event と X-EC-Delivery ヘッダー付きで届き、約 33 時間にわたって再試行されます。
よくある間違い
- フレームワークがすでに解析したボディを検証すること。JSON ミドルウェアはオブジェクトを渡すため、再シリアライズすると TikTok のバイト列が変わることがあります。Webhook のルートで生のボディを読んでください。
- 署名が失敗した配信に 200 を返すこと。TikTok は 200 を見るとそのイベントの送信を止めるため、設定ミスの検証で弾かれた正当なイベントは失われます。4xx の場合、TikTok は最大 72 時間まで再試行を続けます。
- TikTok のサンプルのように、署名を === で比較すること。timingSafeEqual のような定数時間比較では、偽造された署名がどこまで一致したかが明らかになりません。
- easyCoexistence のシークレットを Base64 でデコードすること、whsec_ の接頭辞を取り除くこと。HMAC の鍵は、一度表示されたとおりの文字列全体です。
転送時には、そのアカウント専用のシークレットで X-EC-Signature に署名します。エンドポイントは、Claude または ChatGPT から set_social_webhook_destination で、または PUT /channels/{id}/webhook で設定します。料金は接続 1 件あたり月額 US$ 9 から、接続を増やすほど下がり US$ 0.75 までです。最初の 3 日間は無料です。
よくある質問
TikTok Webhook の x-tt-logid とは何ですか?
各配信の一意の ID を含むヘッダーです。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 は拒否します。
続きを読む
最初のチャンネルを 2 分で接続しましょう。
プラットフォームの審査を待つ必要はありません。WhatsApp、Instagram、TikTok などのチャンネルを接続して、AI に投稿、返信、レポートを任せてみてください。
- 3 日間無料
- いつでも解約可能
- 公式 API のみ使用
- 24/7 監視
確認日