UnifyPort 帳號 Webhook:為何工作區收不到部分事件
如果 UnifyPort 工作區 Webhook 能收到其他訊息帳號的事件,卻收不到某個帳號的事件,請先檢查該帳號的獨立 Webhook 設定。帳號設定會覆寫工作區設定。 獨立端點處於 inactive,或沒有訂閱特定事件,都不會讓事件自動轉往工作區。刪除最後一個獨立端點,才會對後續首次投遞恢復繼承;這不代表補送舊事件。
重點摘要
- 工作區端點與帳號端點是不同設定範圍,不是主備配對。
- 必須分別查詢:未帶帳號參數的清單只包含工作區端點。
- 帳號端點清單為空,表示沒有獨立設定,不等於沒有接收路徑。
- 停用仍保留覆寫關係;恢復繼承需要移除最後一個獨立端點。
- 路由、事件訂閱、驗簽與帳號連線狀態應分開檢查。
哪一層設定決定事件去向?
建立 Webhook 端點文件定義了選填的請求主體欄位 account_id:提供此欄位會將新端點綁定到訊息帳號;省略則建立工作區端點。回應中的獨立端點包含 account_id,工作區端點則省略此欄位。
修改訂閱前,先判斷路由:
| 帳號獨立設定 | 工作區繼承 | 應檢查的項目 |
|---|---|---|
| 沒有獨立端點 | 生效 | 工作區端點狀態與訂閱 |
| 有 active 獨立端點且訂閱符合 | 被覆寫 | 帳號接收服務與簽章設定 |
| 有獨立端點但全部 inactive | 不自動回退 | 是否仍需要獨立設定 |
| active 獨立端點未訂閱目標事件 | 不自動回退 | 帳號端點的訂閱 |
| 最後一個獨立端點已刪除 | 後續首次投遞恢復繼承 | 工作區接收能力與新事件測試 |
假設工作區收集器訂閱 message.received,某帳號的獨立端點卻只訂閱 account.status.updated。這是設定範例,不是實際事故。工作區不會補上帳號篩選器遺漏的訊息事件;應修正帳號設定,或明確決定恢復繼承。
事件篩選指南處理「選哪些事件」;這裡先回答的是:哪個設定範圍負責這個帳號的投遞?
用兩次唯讀請求查看兩個範圍
兩次請求使用同一個伺服器端 X-Api-Key,由金鑰決定工作區。以下僅示範請求路徑,請將 acc_example 換成帳號查詢傳回的實際公開 ID:
GET /v1/webhook-endpoints
GET /v1/webhook-endpoints?account_id=acc_example
列出 Webhook 端點文件說明:第一次只傳回工作區端點;第二次只傳回該帳號的獨立設定,不包含繼承的工作區端點。因此,第二次成功回應中的 data: [] 表示沒有獨立端點,並非沒有 Webhook 路徑。
記錄端點 ID、帳號綁定、URL、status、subscribed_events、signing_enabled 和重試策略。inactive 項目也會影響繼承,不能忽略。診斷紀錄不要包含金鑰或訊息內容。
參數名稱必須是 account_id。空值、純空白、重複參數或不同大小寫都不等於省略。明確指定的帳號不存在或不屬於目前工作區,會傳回 404 account_not_found;請修正帳號和工作區,不要當成空清單。
兩層設定都正確時,再分別確認授權與 runtime 狀態,追蹤一筆支援的新事件是否通過接收端驗證並寫入持久儲存。不要因為錯誤 URL 沒有流量就重啟正常的帳號。
修復獨立設定,還是恢復繼承?
保留帳號專用接收服務
透過更新 Webhook 端點修正既有端點的 URL、啟用狀態或訂閱,並保留已確認的簽章與重試設定。空 signing_secret 會停用簽章,不要將未簽章的範例直接用於正式環境。
同一帳號已有 active 獨立端點時,再建立 active 獨立端點可能傳回 409 account_webhook_already_exists,數字代碼為 40008。將另一端點從 inactive 改為 active 也適用此限制。既有 active 端點保持 active 進行更新則允許,包括歷史上留下的多個 active 設定;系統不會自動清除這些舊設定。此名額規則不限制工作區端點。
帳號綁定不能修改。更新時提供 account_id 只用於驗證原歸屬,省略則保留歸屬。省略或傳入 null 都不能將帳號端點改成工作區端點,也不能將既有工作區端點重新指派給帳號。
回到工作區接收服務
先確認工作區接收端已啟用,訂閱所需事件,且驗簽與持久儲存皆已就緒。與帳號專用工作流程的負責人確認影響。
再透過刪除 Webhook 端點明確移除獨立設定。逐一檢查:留下 inactive 端點仍會保留帳號設定。重新查詢帳號範圍,確認沒有任何獨立端點。刪除成功傳回 204,沒有回應主體。
這是路由變更,不是一般維護建議。若只是暫停 CRM 或 AI 處理,Webhook 維護方式比較說明了為何暫停下游 worker 通常比改動端點更合適。
驗證新路徑,不宣稱歷史已恢復
設定變更後,送出受控的新測試訊息。在預期接收端確認帳號與事件,依照投遞契約驗簽,完成持久儲存後才確認接收。下游處理結果應另外驗證。
以上是建議的驗收步驟,不是已在你的工作區執行的測試。設定請求逾時後,先讀取目前狀態再決定是否重複修改。繼承規則針對後續首次投遞,不能推定所有在途請求的行為。
UnifyPort 非官方介面提供統一事件路徑,不保證重播遺漏的資料。新測試成功只證明新路徑可用,不證明先前缺漏期間的事件已補齊。
常見問題
停用帳號端點後,工作區會接手嗎?
不會。inactive 獨立設定仍覆寫工作區。移除最後一個獨立端點才會對後續首次投遞恢復繼承。
將工作區訂閱改為萬用字元能解決嗎?
不能解決帳號覆寫問題。應修改實際生效的帳號設定,或有計畫地移除它以恢復繼承。
帳號端點清單為空代表什麼?
成功的空結果表示沒有獨立端點。請繼續查詢工作區清單,檢查繼承的設定。錯誤回應不是空結果。
下一步與參考資料
先查看列出 Webhook 端點,比較兩個範圍後再決定修改。
官方產品文件核對日期:2026-11-15。
讓訊息接入變成一條穩定的產品管線。
先用統一 API 跑通傳送,再用標準事件把所有入站訊息接回業務系統。