← 所有文章
指南

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。

UnifyPort API

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

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