TikTok API for Business の Webhook 設定
TikTok の API for Business は、開発者アプリごと、イベントタイプごとに 1 つのコールバック URL へ Webhook を送信します。コールバック URL は、アプリの app_id と secret を使って POST /business/webhook/update/ で設定します。event_type VIDEO は投稿公開の 4 つのイベントを、COMMENT は comment.update を購読します。各配信は HTTPS の POST で届き、アプリの secret を鍵とする HMAC-SHA256 で署名された値が Tiktok-Signature ヘッダーに含まれます。
easyCoexistence は、自社アプリで TikTok のコメント Webhook を購読し続け、TikTok の署名を検証して、アカウントの各コメントイベントを、独自の secret で署名したうえでお客様の HTTPS エンドポイントに渡します。
HTTP 200 で応答されなかった配信を、指数バックオフで再試行し、破棄するまでの期間。
1 つの item_list で comment.update を絞り込める投稿 ID の最大数。
TikTok が各配信に付与する webhook-schema-version ヘッダーの現在の値。
TikTok のリファレンスに記載された、アプリ ID と secret で認証する Webhook 設定エンドポイント。
Tiktok-Signature のアルゴリズム: タイムスタンプ、ドット、本文を連結したものを、アプリの secret を鍵として HMAC-SHA256 で計算し、16 進数で表記します。
comment.update に必要な TikTok Accounts のアプリ権限。投稿公開のイベントには Business Content が必要です。
TikTok アカウントのアプリはどの Webhook イベントを受け取れますか?
2 つのカテゴリがあり、それぞれ個別の event_type として購読します。VIDEO は /business/video/publish/ または /business/photo/publish/ を通じて公開された投稿を対象とし、COMMENT は API または TikTok アプリから公開された、アカウントの写真投稿と公開動画へのコメントを対象とします:
購読の前に必要なものは何ですか?
API for Business へのアクセス、開発者アプリ、そしてそれを承認した TikTok アカウントが必要です。TikTok の購読ガイドでは、カテゴリごとに権限が追加されており、コメントイベントには各所有者からのスコープが必要です:
- 投稿公開のイベント: アプリに TikTok Accounts の Business Content 権限が必要です。
- コメントのイベント: アプリに TikTok Accounts の Business Comment 権限が必要です。
- comment.update: 所有者が付与し、有効に保たれている comment.list スコープが必要です。
- HTTP 200 をすぐに返す HTTPS のコールバック URL。
購読はどのように行いますか?
event_type ごとに 1 回、POST /business/webhook/update/ を送信します。リクエストボディには app_id、secret、event_type(VIDEO または COMMENT)、callback_url を指定します。COMMENT の場合は item_list を指定することもできます。レスポンスには app_id、event_type、callback_url、設定されている場合は item_list が含まれます。同じ event_type で再度呼び出すと、コールバック URL が置き換えられます。
curl -X POST 'https://business-api.tiktok.com/open_api/v1.3/business/webhook/update/' \
-H 'Content-Type: application/json' \
-d '{
"app_id": "<APP_ID>",
"secret": "<APP_SECRET>",
"event_type": "COMMENT",
"callback_url": "https://hooks.example.com/tiktok/"
}'
{
"code": 0,
"message": "OK",
"request_id": "<REQUEST_ID>",
"data": { "app_id": "<APP_ID>", "callback_url": "https://hooks.example.com/tiktok/", "event_type": "COMMENT" }
}item_list はコメントイベントをどのように絞り込みますか?
comment.update を、指定された投稿に限定します。/business/video/list/ から最大 100 件の ID を指定でき、最初に送信したリストがその後のアプリのモードを決定します:
item_listを指定した最初の COMMENT 呼び出し: 指定された投稿のイベントのみが届きます。- 以降に
item_listを指定した呼び出し: 新しい投稿が既存のリストに追加されます。 item_listを指定しない COMMENT 呼び出し(それ以前に設定がない場合): アプリを承認したアカウントの投稿のイベントが届きます。item_listを指定しない COMMENT 呼び出し(リストが存在する場合): 設定済みの投稿はそのまま維持されます。
購読を確認または削除するには?
app_id、secret、event_type を付けて GET /business/webhook/list/ を呼び出すと、設定が返されます。callback_url は、そのイベントタイプに設定されている場合のみ表示され、item_list は設定されている場合のみ表示されます。app_id、secret、event_type を付けて POST /business/webhook/delete/ を送信すると削除されます。COMMENT の場合、削除リクエストに item_list を指定すると、その投稿のみが削除され、指定しなければすべての投稿のコメントイベントが停止します。
コールバック URL はどのように動作する必要がありますか?
すぐに応答してください。TikTok は HTTPS で JSON を POST し、HTTP 200 以外はすべて配信失敗として扱います。イベントを破棄するまで最大 72 時間、指数バックオフで再試行します。配信は少なくとも 1 回保証されるため、同じイベントが 2 回届く場合があり、処理は冪等でなければなりません。各リクエストには、ログに残しておきたい 3 つのヘッダー(tiktok-signature、webhook-schema-version、x-tt-logid)が含まれ、ボディには client_key、event、create_time(秒単位)、user_openid(アカウントの business_id)、そしてシリアライズされた JSON 文字列の content が含まれます。
Tiktok-Signature はどのように検証しますか?
ヘッダーを、まずカンマで分割し、次に等号で分割します(t=<unix>,s=<hex>)。t の値、ドット、リクエストボディから署名対象のメッセージを作成し、アプリの secret を鍵として HMAC-SHA256 を計算し、16 進数で表記して s と比較します。次に t の経過時間を確認します。TikTok は配信時刻に署名を付けてリプレイ攻撃を防ぎ、サンプルコードは 5 秒の遅延を許容しています。受信した生のボディをそのまま使うと、JSON を異なる形で再シリアライズしてしまうことを防げます。
import hashlib, hmac, time
def verify_tiktok(raw_body: bytes, header: str, app_secret: str, max_age: int = 300) -> bool:
parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
t, s = parts.get("t", ""), parts.get("s", "")
if not t.isdigit():
return False
expected = hmac.new(app_secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, s) and abs(time.time() - int(t)) <= max_ageeasyCoexistence を通じて TikTok のイベントを受け取るには?
アカウントに送信先を設定します。easyCoexistence は自身のアプリで COMMENT を購読し、TikTok の署名を検証し、TikTok にすぐ応答して、接続済みアカウントの各 comment.update を、そのアカウントに設定された HTTPS エンドポイントに POST します。Claude または ChatGPT から set_social_webhook_destination を呼び出し、account_id と url を指定します。停止する場合は url に null を指定します。署名用の secret が返され、一度だけ表示されます。再度呼び出すと新しい secret が発行されます。投稿公開のイベントは転送されません。代わりに get_tiktok_publish_status で投稿を追跡します。
set_social_webhook_destination { "account_id": "<ACCOUNT_ID>", "url": "https://hooks.example.com/tiktok/" }
=> {
"url": "https://hooks.example.com/tiktok/",
"signing_secret": "whsec_<SECRET>",
"note": "Shown once: store it as a secret. ..."
}Partner API で設定するには?
https://easycoexistence.com/api/v1 に対して、PUT /channels/{id}/webhook を送信します。認証には ec_live_ で始まるキーを Bearer トークンとして使い、ボディには {"url": "https://..."} を指定します。レスポンスには webhook_url、signing_secret、注記が含まれ、{"url": null} を送信すると転送が停止します。URL は公開ホストの HTTPS である必要があります。存在しないチャネルは 404 not_found、削除済みのチャネルは 409 removed、停止中のチャネルは 402 suspended を返します。
curl -X PUT "https://easycoexistence.com/api/v1/channels/$CHANNEL_ID/webhook" \
-H "Authorization: Bearer $EC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://hooks.example.com/tiktok/"}'
{ "webhook_url": "https://hooks.example.com/tiktok/", "signing_secret": "whsec_<SECRET>", "note": "..." }2 つの配信はどう違いますか?
easyCoexistence からの転送は、TikTok 自身の配信と署名や形式が異なるため、一方向けに書かれたレシーバーは他方に対応するための変更が必要です。転送されるペイロードは TikTok のコメントフィールドを保持し、content は解析され、ID は文字列になっています。変わるのは、各配信の署名方法、対象範囲、再試行の仕組みです:
| TikTok to your app | easyCoexistence to your endpoint | |
|---|---|---|
| Header | Tiktok-Signature: t=<unix>,s=<hex> | X-EC-Signature: t=<unix>,v1=<hex> |
| Key | The developer app's secret | The account's signing secret, shown once |
| Events | VIDEO and COMMENT, per app | comment.update, per connected account |
| Body | client_key, event, create_time, user_openid, content as a string | platform, account_id, external_id, entry with content parsed |
| Retries | Up to 72 hours | None: one attempt, 8 seconds, no redirects |
設定方法
- Grant the permissionsGive the developer app Business Content for publishing events and Business Comment for comment events, and have owners grant comment.list.
- Build the callbackServe an HTTPS endpoint that checks Tiktok-Signature and replies 200 before doing any work.
- Subscribe each event typeCall /business/webhook/update/ with app_id, secret, event_type and callback_url, once for VIDEO and once for COMMENT.
- Confirm the configurationCall /business/webhook/list/ for each event_type and check that the callback_url, and any item_list, came back.
- Handle repeatsKey each event on its content, such as comment_id with comment_action, or publish_id with the event name, before acting on it.
よくある間違い
- 応答前にイベントを処理すること。TikTok は即座に 200 を求め、確認応答されない配信を再試行します。作業はキューに入れ、先に応答してください。
- 最初の COMMENT 購読で誤って item_list を送信すること。以降、TikTok は指定された投稿のコメントイベントのみを報告します。
- アクセストークンで検証すること。TikTok は Webhook を、/business/webhook/update/ が受け取るのと同じアプリの secret で署名します。
- 2 つの環境を 1 つのアプリに向けること。イベントタイプごとにアプリにつき callback_url は 1 つだけで、新しい /business/webhook/update/ の呼び出しで置き換えられます。
Claude または ChatGPT から set_social_webhook_destination、または PUT /channels/{id}/webhook で設定できます。接続 1 件あたり月額 US$ 9 から、接続を増やすほど下がり US$ 0.75 まで。最初の 3 日間は無料です。
よくある質問
TikTok の Webhook 配信にはどのヘッダーが含まれますか?
tiktok-signature、webhook-schema-version(現在は v1.0)、x-tt-logid(配信の ID)です。JSON ボディには client_key、event、create_time、user_openid、content が含まれます。
動画が公開されたとき、TikTok は Webhook を送信しますか?
はい。event_type VIDEO で送信されます。TikTok がファイルのダウンロードと確認を完了すると post.publish.complete が送信され、続いて投稿が公開されると post_id を含む post.publish.publicly_available が送信されます。
TikTok は失敗した Webhook を何時間まで再試行しますか?
指数バックオフで最大 72 時間再試行し、その後イベントは破棄されます。配信は少なくとも 1 回保証されるため、重複を想定してください。
easyCoexistence の TikTok アプリに独自のコールバックを登録できますか?
いいえ。アプリの Webhook 設定は easyCoexistence が管理します。代わりに set_social_webhook_destination で、アカウントのコメントイベントをお客様に送信するよう設定できます。
続きを読む
最初のチャンネルを 2 分で接続しましょう。
プラットフォームの審査を待つ必要はありません。WhatsApp、Instagram、TikTok などのチャンネルを接続して、AI に投稿、返信、レポートを任せてみてください。
- 3 日間無料
- いつでも解約可能
- 公式 API のみ使用
- 24/7 監視
確認日