Webhook 維護：暫停 worker、停用端點，還是刪除？

如果維護的只是下游業務，優先讓 webhook 接收器繼續驗證簽章並持久化事件，暫停消費事件的 worker。停用 UnifyPort 端點會將狀態設為 inactive，但保留端點設定；刪除則移除端點。兩者都不是文件承諾的「暫停後補送」服務。先確認要停止哪一層，再選擇控制方式。

重點

• CRM、AI 流程或 worker 維護時，優先在持久化接收之後暫停業務處理。
• 只有確實需要停用端點時才執行停用，並規劃潛在投遞缺口的處理方式。
• 刪除用於端點退役，不應作為臨時部署開關。
• 返回 503 不能換取維護時間：UnifyPort 會立即重試，沒有退避等待。

三種控制方式的差異

第一種是建議的應用程式架構，後兩種是 UnifyPort 文件提供的控制平面操作。

控制方式	改變什麼	仍須自行負責什麼
暫停應用程式 worker	消費者停止處理，正常的接收器繼續持久化事件	佇列容量、保留策略、恢復檢查點及副作用冪等
停用端點	狀態變為 inactive，端點不被刪除	記錄中斷、驗證重新啟用、調查遺漏區間
刪除端點	端點資源被移除	再次需要服務時建立並驗證新端點

停用端點文件對應 POST /v1/webhook-endpoints/{endpoint_id}/deactivate。刪除端點文件對應 DELETE /v1/webhook-endpoints/{endpoint_id}，成功返回 204 No Content。

這些操作控制的是 webhook 端點，不等於帳號登出、執行階段連線停止，也不等於取消應用程式已接收的工作。已領取工作的 worker 仍可能完成動作；若要停止這些副作用，需要應用程式自己的處理控制。

為什麼優先暫停 worker

假設團隊要部署 CRM 整合，但仍希望 LINE 與 WhatsApp 訊息進入收件匣。這是架構示例，不是客戶案例或已達成的成果。

將接收路徑與 CRM 分開：

1. 使用原始請求位元組驗證簽章與時間戳記。
2. 驗證事件並提交至持久化儲存。
3. 返回成功確認。
4. 由獨立 worker 執行 CRM 寫入、AI 呼叫或通知。

暫停消費者前，確認接收儲存在維護期間持續可用。為佇列成長及資料保留設定操作界線，並指定儲存故障的處理負責人。記憶體陣列不能充當可承受程序重新啟動的維護緩衝區。

部署後，從已提交的處理狀態繼續消費。入口返回過 2xx，不表示積壓工作已完成。Webhook-first 整合檢查清單說明初始持久化界線；維護還需要分別控制消費者何時可以執行動作。

如果要維護的是接收儲存本身，這個模式並不足夠。接收器和儲存都必須離線時，應準備經驗證的替代接收路徑，或明確接受並記錄中斷，不能未經驗證就承諾持續收集。

為什麼錯誤回應不是暫停機制

投遞契約說明：連線錯誤及 408、429、5xx 會立即重試。retry_policy.max_attempts 表示首次請求之後的重試次數，預設三次；沒有退避，也不遵循 Retry-After。其他 4xx 會停止自動投遞並將事件標記為死信。

因此，部署期間持續返回 503 可能耗盡嘗試次數，而不是將投遞延後到服務恢復。返回 200 卻捨棄內容更不可取：這等於確認了尚未持久化的資料。死信也不代表系統承諾提供公開重播操作。

維護期間繼續驗證簽章。空的 signing_secret 會停用簽章，不會暫停投遞。需要更換憑證時，採用獨立的簽章密鑰輪替程序，不要將驗證變更與端點退役混在一起。

確實要停用時，設定恢復門檻

變更前，使用取得端點設定記錄端點 ID、URL、狀態、訂閱事件、簽章狀態和重試策略。實際密鑰留在受保護設定中，不寫入變更紀錄。同時列出依賴此端點的下游流程。

停用選定端點後，再讀取設定確認狀態。將操作時間及結果與應用程式佇列狀態分開記錄。公開文件沒有說明在途請求全部排空的保證，也沒有承諾補送停用期間的事件；成功回應不能證明這兩點。

恢復時使用更新端點，將 status 設為 active 並提交經審核的設定。保留預期 URL、訂閱、重試策略和非空簽章密鑰，不要直接複製範例中的停用或無簽章設定至正式環境。

重新讀取設定，確認 signing_enabled: true，再向已連接的訊息帳號傳送受控測試訊息。追蹤對應 message.received，檢查簽章驗證、持久化及目標 worker 處理。這只能證明新事件路徑正常，不能證明停用期間的資料已恢復。

若控制平面請求逾時，先查詢目前端點，再決定後續變更。保留不含秘密的請求診斷資訊。接收器安靜不代表停用已完成；重新啟用成功也不代表端到端業務已恢復。

刪除與恢復的界線

只有確認不再需要端點並記錄其相依關係後才刪除。刪除成功沒有 JSON 回應主體，不要嘗試解析。日後建立替代端點是重新佈建，不是恢復舊端點遺漏的投遞。

UnifyPort 的非官方介面提供標準化訊息帳號事件，但沒有通用 REST 訊息歷史讀取 API，也不保證遺漏內容重播。有限的 WhatsApp 歷史機制不是跨通道維護恢復保證。

恢復已儲存工作時，依文件定義的界線去重：普通事件重試沿用 X-Device-Event-Id；conversation.history 批次需要逐訊息合併，不能僅依此標頭全域去重。傳送等業務副作用仍需要獨立的冪等控制。

常見問題

停用會保留端點嗎？

會。狀態變為 inactive，端點不會刪除。但這不構成積壓保留或重播保證。

可以只暫停 AI 流程嗎？

可以在應用程式中暫停該消費者，讓接收器繼續驗證及持久化。這不是額外的 UnifyPort API 設定。

部署時應該刪除再建立嗎？

通常不應該。下游維護優先暫停消費者；需要中斷端點時，則事先規劃中斷。刪除是退役決策。

下一步與參考資料

先閱讀投遞契約，寫清維護實際停止哪一層，再修改正式環境設定。

產品資料核對日期：2026-10-06。

• 停用 webhook 端點
• 更新 webhook 端點
• 刪除 webhook 端點
• 投遞、確認和重試