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;應修正 ID 和工作空間,不要當作空清單。
兩層設定都正確時,再分別確認授權與 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 跑通發送,再用標準事件將所有入站訊息接返去業務系統。