收不到 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 路徑建立正式環境解析器,也不要把自製範例當成正式酬載。先安全保留已驗證信封,在受控環境檢查;確認實際契約後再啟用依賴內部欄位的自動化。
使用受控驗證,不要反覆重新連線
以下是建議的診斷流程,不是已完成的測試結果:
- 確認目標環境支援功能,並選定目前帳號擁有的貼文。
- 保持自動回覆關閉,準備簽章接收流程及正確訂閱。
- 套用布林輪詢設定,執行一次所需連線操作。
- 由獲授權的測試參與者新增一則可辨識留言,安全保存原生參照。
- 分別追蹤請求抵達、驗簽、持久化、去重與背景處理。
缺少訊號時,保留去識別化後的帳號與端點識別碼、設定及操作結果、時間,以及可取得的請求 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。
讓訊息接入變成一條穩定的產品管線。
先用統一 API 跑通傳送,再用標準事件把所有入站訊息接回業務系統。