TikTokのコメントWebhookが届かない?ポーリングと配信先を確認
UnifyPortの post.comment.created を購読するだけでは、TikTokのコメントポーリングは開始されません。既定では無効です。provider_data.enable_comment を真偽値の true に設定し、起動または再接続で適用します。オンライン中の変更には再接続が必要です。配信先も別に確認してください。起動成功は設定適用の証明ではなく、通知がないこともコメントがない証明にはなりません。
要点
- コメントの検出、接続への設定適用、配信先、アプリ側の処理を分けます。
- 有効化前に対象環境での利用可否と受信準備を確認します。
- アカウント専用Webhook設定はワークスペース設定より優先され、無効状態や購読不一致でも自動的には戻りません。
- 通知はベストエフォートであり、完全な履歴でも自動返信の許可でもありません。
どのWebhookを設定しているか確認する
TikTokの公式開発者向けWebhook一覧には、独自のイベント名とリクエスト形式があります。一方、UnifyPortの post.comment.created リファレンスは、識別と自分の投稿の所有確認を経たTikTokコメント通知を正規化する、別の契約です。
TikTok Developer PortalにUnifyPortのイベント名を入力しても、UnifyPortの設定にはなりません。公式TikTok Webhookと、既存アカウントを接続する非公式インターフェースは分けて扱います。本稿は後者についてであり、TikTok ShopのカスタマーサービスメッセージやDMの設定ではありません。
未接続の場合は、先に TikTokのQR認証手順を完了してください。認証済みで接続が稼働していることは前提条件であり、コメントポーリング有効化の証拠ではありません。
四つの境界を順に調べる
| 境界 | 確認する証拠 | 証明できないこと |
|---|---|---|
| 検出 | 環境が機能に対応し、ポーリングを明示的に有効化した | 過去の全コメントを取得できる |
| 接続 | 設定変更後に必要な起動または再接続を行った | 起動成功だけで設定が適用された |
| 配信先 | 正しい範囲、有効状態、一致する購読 | 上流でイベントが生成された |
| 処理 | 検証済みイベントを永続保存し処理した | 全コメントが届いた、返信が公開表示された |
この順序なら、無効なポーリングを直すために署名シークレットを交換したり、購読の不一致を直すために再接続を繰り返したりせずに済みます。
1. 画面のチェックではなく実際の設定を見る
アカウント更新リファレンスでは、provider_data.enable_comment は真偽値のみを受け付けます。true と false は有効ですが、文字列、数値、null は 400 invalid_request になります。保護された設定管理で、意図した値と実際のAPI結果を記録します。
provider_data は省略すると維持され、{} は消去を意味します。一部のネストしたフィールドを送れば既存設定全体にマージされるとは考えないでください。管理された設定元から必要な値を保った更新内容を作り、秘密情報をログに残さないようにします。機密設定が省略された読み取り結果は、完全な設定バックアップではありません。
オンラインのアカウントでは、更新後に一度の明示的なランタイム再接続を計画します。認証済みで停止中なら、必要に応じて文書化された起動手順を使います。自動復旧ワーカーと調整し、競合する操作を避けてください。起動成功という応答は「コメントポーリング検証済み」を意味しません。
2. このアカウントに適用される配信先を確認する
Webhookエンドポイント一覧で、ワークスペースとアカウント専用設定をそれぞれ確認します。account_id を付けない一覧はワークスペース設定、付けた一覧はそのアカウントの独立設定です。後者に継承されたワークスペース設定は含まれません。
エンドポイント設定リファレンスでは、アカウント設定がワークスペース設定に優先します。独立したエンドポイントが無効でも、購読が一致しなくても、ワークスペースへ自動的に配信されるわけではありません。ワークスペースの受信サービスが正常というだけでは、このアカウントの経路は確認できません。
適用される端点の状態と購読を調べ、post.comment.created を明示するか、["*"] など文書化された広い選択を使います。必要なメッセージや認証イベントの購読は残してください。イベントフィルターの解説が扱うのは配信対象の選択であり、上流のポーリング開始ではありません。
診断の実験として独立したエンドポイントを削除しないでください。最後の独立設定を削除すると、その後の初回配信はワークスペース設定を継承するため、将来の配信先が変わります。意図した経路変更として確認が必要です。
3. コメントフィールドを推測せず受信を検証する
UnifyPortの配信契約に従います。署名を有効にした場合、X-Device-Timestamp、ピリオド、未加工のリクエスト本文を連結した値のHMAC-SHA256で X-Device-Signature を検証し、タイムスタンプの鮮度も確認します。検証済みイベントを永続保存してから2xxを返し、このイベント種別はワークスペース内のイベント id で重複排除します。
イベント資料は共通エンベロープの id、type、provider、account_id、occurred_at、data を確定していますが、詳細フィールド資料と実際の取得サンプルは準備中としています。推測した data.comment のパスで本番パーサーを作ったり、自作サンプルを正式なペイロードとして扱ったりしないでください。認証済みのエンベロープを管理された環境で確認し、内部フィールドに依存する自動化の前に実際の契約を確かめます。
再接続ループではなく管理されたテストを使う
以下は推奨する診断手順であり、実施済みのテスト結果ではありません。
- 対象環境で機能が利用可能か確認し、接続アカウントが所有する投稿を選びます。
- 自動返信は無効のままにし、署名付き受信と正しい購読を準備します。
- 真偽値の設定と必要な接続操作を一度適用します。
- 許可されたテスト参加者が識別できるコメントを投稿し、そのネイティブ参照を安全に保管します。
- リクエスト到着、署名検証、永続保存、重複排除、ワーカー処理を別々に追います。
届かない場合は、機密を除いたアカウント・端点の識別子、設定と操作結果、時刻、取得できたリクエストIDを調査用に残します。固定の到着期限は約束できません。通知には遅延、重複、順序の変化、欠落があり得ます。一度成功しても、そのテストで経路が動いたこと以上は証明しません。
無効化してもキュー内のイベントは撤回されない
業務アクションをすぐ止めたい場合、まずアプリ側のコメントアクションワーカーを停止します。その後 enable_comment: false を適用し、オンラインなら必要な再接続を行います。既にキューにある配信は、保持方針に沿って安全に受信し続けます。無効化はそれらを撤回しないと明記されています。
ワーカー停止はアプリ側の対策で、新しいAPIフィールドではありません。DM処理を続ける必要があれば独立させます。無効化後に届いたイベントだけを見て、設定失敗と決めつけないでください。
返信を有効にする際は、別のトップレベルコメントへの返信手順を使います。parent_comment_id がないことは返信可能なトップレベル対象の証明にならず、通知は以前の返信に対する保証された受領証でもありません。
よくある質問
post.comment.createdの購読でポーリングは始まりますか?
いいえ。フィルターと provider_data.enable_comment は別の制御です。接続への設定適用も必要です。
runningならコメント監視も正常ですか?
いいえ。接続状態を表すだけです。設定、経路、管理された観察は別々に確認します。
通知がなければ新しいコメントもありませんか?
そうとは限りません。通知は欠落し得ます。無通知を完全な件数や履歴として表示しないでください。
DMの自動返信トリガーに使えますか?
いいえ。これは message.received ではなくコメント通知です。公開返信は独立した操作として、投稿とコメント対象を確認してから実施します。
次のステップと資料
まず post.comment.created リファレンスを読み、本番設定を変更する前に未確認の境界を記録してください。
公式資料の確認日:2026-11-14。
メッセージ連携を安定したプロダクトパイプラインへ。
まずは 1 つの API で送信を始め、標準イベントですべての inbound メッセージを業務システムへ戻しましょう。