收不到 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 二維碼授權流程。授權完成及連線運行只是排查前提,不是留言輪詢已開啟的證據。
按四個邊界檢查
| 邊界 | 應查看的證據 | 不能據此證明甚麼 |
|---|---|---|
| 留言發現 | 環境支援功能,並已明確開啟輪詢 | 所有歷史留言都會被找到 |
| 連線 | 修改設定後執行所需啟動或重新連線 | 啟動成功即表示輪詢設定已套用 |
| 路由 | 端點範圍正確、狀態啟用、訂閱匹配 | 上游已產生事件 |
| 處理 | 事件驗簽通過、持久化並完成處理 | 所有留言均已送達,或回覆已公開顯示 |
這個順序可以避免為了未開啟的輪詢更換簽名密鑰,也不會用反覆重新連線處理訂閱過濾問題。
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 跑通發送,再用標準事件將所有入站訊息接返去業務系統。