ログイン無料トライアルを開始
easyCoexistence 公式 API

TikTok Webhook を検証する:署名ヘッダーと確認方法

TikTok の API for Business は、各 Webhook 配信を Tiktok-Signature ヘッダーで署名します。形式は t=<unix seconds>,s=<hex> で、s は t の値、ドット、リクエストボディを連結したものに対する HMAC-SHA256 です。鍵は開発者アプリのシークレットです。検証するには、受信した生のボディに対して同じ HMAC を再計算し、s と定数時間で比較します。そして古い t は拒否します。

easyCoexistence は、接続済みアカウントのコメントイベントを受け取るたびに TikTok の署名を確認し、そのアカウントのコメントイベントを HTTPS エンドポイントへ転送します。

t and s

Tiktok-Signature の 2 つの要素は、その配信の Unix タイムスタンプ(秒)と、TikTok がその配信に対して生成した署名です。

5 seconds

TikTok の Node.js サンプルにある acceptableDelay は、正しく署名されていても、それより古い配信を拒否する値です。

x-tt-logid

各配信の一意の ID を含むヘッダーです。TikTok は障害調査のために、これを記録するよう受信側に求めています。

BRAND_MENTION

メンション Webhook のイベントタイプです。その購読ガイドは、同じ署名検証を参照するよう案内しています。

v1

easyCoexistence の X-EC-Signature ヘッダーの署名部分です。t、ドット、生のボディに対する HMAC-SHA256 です。

Tiktok-Signature ヘッダーはどのような形式ですか?

2 つの要素をカンマで区切ります。t は、その配信の Unix タイムスタンプ(秒)です。s は署名で、16 進数の 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.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 で、鍵はアカウントの署名シークレットです:

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 の差を計算して、許容できるかどうかを判断します。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 から読み取ってください:

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 を呼び出すと新しいシークレットが返され、古いものはただちに無効になります。各転送は 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 の鍵は、一度表示されたとおりの文字列全体です。
EasyCoexistence で実現する

転送時には、そのアカウント専用のシークレットで 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 監視

確認日