← 所有文章
指南

收不到 TikTok 留言 Webhook?檢查輪詢設定與端點路由

訂閱 UnifyPort 的 post.comment.created 不會自動啟用 TikTok 留言輪詢。輪詢預設關閉:需將 provider_data.enable_comment 設為布林值 true,再透過啟動或重新連線套用;線上帳號變更設定後需要重新連線。接收端點也要另外檢查。啟動成功不代表輪詢設定已套用,沒有 webhook 也不代表沒有人留言。

重點整理

  • 分開檢查留言發現、連線設定、端點路由及應用程式處理。
  • 啟用前先確認環境支援,並準備好接收端。
  • 帳號獨立 webhook 設定可覆蓋工作空間設定;停用或訂閱不符時不會自動改走工作空間端點。
  • 通知是盡力提供的訊號,不是完整歷史,也不是自動回覆的許可。

先確認你設定的是哪一種 webhook

TikTok 的官方開發者 webhook 目錄定義自己的事件名稱及請求結構。UnifyPort 的 post.comment.created 文件則是另一套契約:完成識別與自有貼文歸屬檢查後,產生標準化的 TikTok 留言通知。

在 TikTok Developer Portal 填入 UnifyPort 事件名稱,不會替你完成 UnifyPort 設定。官方 TikTok webhook 與連接既有帳號的非官方介面應分開處理。本文討論後者,不是 TikTok Shop 客服訊息或私訊接入。

尚未連接訊息帳號時,請先完成 TikTok QR Code 授權流程。授權完成及連線運作是排查前提,不是留言輪詢已啟用的證據。

依序檢查四個邊界

邊界應檢查的證據不能證明的事項
留言發現環境支援功能,並已明確啟用輪詢所有歷史留言都會被找到
連線設定變更後執行所需啟動或重新連線啟動成功等於輪詢設定已套用
路由端點範圍正確、狀態啟用、訂閱符合上游已產生事件
處理事件驗簽通過、持久化並完成處理全部留言已送達,或回覆已公開顯示

這個順序能避免為了未啟用的輪詢更換簽章密鑰,也不會以重複連線處理訂閱過濾問題。

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 路徑建立正式環境解析器,也不要把自製範例當成正式酬載。先安全保留已驗證信封,在受控環境檢查;確認實際契約後再啟用依賴內部欄位的自動化。

使用受控驗證,不要反覆重新連線

以下是建議的診斷流程,不是已完成的測試結果:

  1. 確認目標環境支援功能,並選定目前帳號擁有的貼文。
  2. 保持自動回覆關閉,準備簽章接收流程及正確訂閱。
  3. 套用布林輪詢設定,執行一次所需連線操作。
  4. 由獲授權的測試參與者新增一則可辨識留言,安全保存原生參照。
  5. 分別追蹤請求抵達、驗簽、持久化、去重與背景處理。

缺少訊號時,保留去識別化後的帳號與端點識別碼、設定及操作結果、時間,以及可取得的請求 ID。不要承諾固定抵達時間:文件允許延遲、重複、順序不一及遺漏。一次成功觀察只證明該次測試的路徑可用,不代表全面涵蓋。

關閉輪詢不會撤回佇列中的事件

若要立即停止業務動作,先暫停應用程式中的留言動作背景工作,再套用 enable_comment: false,並為線上帳號執行所需重新連線。依自己的保留政策繼續安全接收已排入佇列的投遞;文件明確指出關閉不會撤回它們。

暫停背景工作是應用程式防護,不是新的 API 欄位。若私訊仍需處理,讓它獨立運作。關閉後仍收到事件,也不能直接判定設定失敗。

日後啟用回覆時,請使用獨立的頂層留言回覆流程。缺少 parent_comment_id 不代表目標是可回覆的頂層留言,通知也不是先前回覆的保證回執。

常見問題

訂閱 post.comment.created 就會啟用輪詢嗎?

不會。webhook 過濾與 provider_data.enable_comment 是不同控制項,連線也需要套用設定。

running 代表留言監控正常嗎?

不是。它描述連線狀態;設定、路由及受控觀察需要分別確認。

沒事件就代表沒有新留言嗎?

不是。通知可能遺漏,不應將靜默當成完整留言統計或封存資料。

可以用它觸發私訊自動回覆嗎?

不可以。它是留言通知,不是 message.received。公開回覆應是另一個動作,先驗證貼文與留言目標。

下一步與參考資料

先閱讀 post.comment.created 參考,記錄尚未驗證的邊界,再變更正式環境設定。

官方資料核對日期:2026-11-14。

UnifyPort API

讓訊息接入變成一條穩定的產品管線。

先用統一 API 跑通傳送,再用標準事件把所有入站訊息接回業務系統。