Webhook 概觀介紹¶

當你的系統需要即時得知 U-Office Force X 裡發生了什麼事，例如一張表單被簽核完成、一筆申請被退回，過去傳統做法是定期輪詢（Polling）API 去問「有沒有新東西？」。問題在於：大多數時候答案都是「沒有」，因此白白浪費了運算資源和網路流量，卻無法實現真正的即時反應。

U-Office Force X 所提供的 Webhook 解決的正是這個問題：不再需要由你主動去問，而是事件發生時，由 U-Office Force X 系統主動通知你的系統。

什麼是 Webhook¶

Webhook 是一種由事件驅動的通知機制。當來源系統（U-Office Force X）發生特定事件時，它會主動發送一個 HTTP POST 請求到你預先設定好的 URL，將事件相關資料即時推送給你的系統。

用一個簡單的比喻來說：Polling 像是你每隔五分鐘打電話問餐廳「餐點好了嗎？」，而 Webhook 像是餐廳準備好餐點後直接打電話通知你來取餐，很明顯的後者方式會更有效率。

Webhook　運作機制¶

Webhook 的運作流程包含四個步驟：

sequenceDiagram
    participant 你的系統 as 你的系統（接收端）
    participant UOFX as U-Office Force X（來源端）

    你的系統->>UOFX: ① 註冊 Webhook（設定接收 URL + 事件類型）
    Note over UOFX: 事件發生（例：文件中心文件異動事件）
    UOFX->>你的系統: ② 發送 HTTP POST（夾帶事件資料）
    你的系統-->>UOFX: ③ 回傳 HTTP 200（確認收到）
    Note over UOFX: 若未收到回應，執行重試機制
    UOFX->>你的系統: ④ 重試通知（依重試策略）

① 註冊 Webhook 通道：你在來源系統必須提供一個接收通知的 URL，並且在 U-Office Force X 中指定要監聽哪些事件類型。

② 推送：當指定的事件發生時，來源系統會對你的 URL 發送 HTTP POST 請求，Request Body 中包含事件的詳細資料（JSON 格式）。

③ 確認：你的系統收到請求後，應回傳 HTTP 200 OK 表示已成功接收。

④ 重試：如果來源系統在一定時間內沒有收到你的成功回應（例如你的伺服器暫時無法連線），通常會依照重試策略再次發送通知，確保事件不會遺漏（達重試次數上限則停止重試）。

Webhook 與 Polling 的差異¶

比較項目	Webhook（推送模式）	Polling（輪詢模式）
觸發方式	事件發生時主動通知	定期發送請求詢問
即時性	接近即時	取決於輪詢間隔
資源消耗	只在有事件時才有流量	無論有無事件都持續消耗
實作複雜度	需建立可公開存取的 HTTP 端點	只需能發出 HTTP 請求
適用場景	事件驅動、需即時反應	事件頻率極高、或無法建立公開端點

常見運用場景¶

Webhook 廣泛應用於系統整合與自動化流程中，以下是幾個典型場景：

業務流程自動化

表單簽核完成後，自動將結果回寫至 ERP 系統
請假申請核准後，自動更新出勤系統的假別額度
採購單審批通過後，自動觸發供應商通知信

即時資料同步

組織架構異動時，即時同步至第三方 HR 系統
人員到職或離職時，自動更新 AD 帳號與權限

通知與監控

重要表單被退回時，即時推送訊息至 Teams 頻道
特定流程超時未處理時，觸發預警通知給主管

U-Office Force X 的 Webhook 支援¶

U-Office Force X 提供完整的 Webhook 機制，讓你的外部系統能在關鍵時候即時收到通知，無需透過 SDK 或 OpenAPI 輪詢查詢。

主要特性：

事件訂閱：可針對特定事件進行訂閱（依 U-Office Force X 發展會提供更多不同的事件通知），只接收你關心的通知
安全驗證：每次推送都包含簽章資訊，你的系統可驗證請求確實來自 U-Office Force X，防止偽造
重試機制：當你的接收端暫時無法回應時，系統會自動重試，確保事件通知不遺漏
彈性整合：只要你的系統能接收 HTTP POST 請求，無論使用什麼程式語言或框架，都能與 Webhook 整合
Webhook 與 SDK Callback 的差異：如果你已經在使用 SDK 的 Callback 機制，可能會好奇兩者有什麼不同。簡單來說，SDK Callback 是在透過 SDK 起單時設定的回呼，屬於「你主動發起操作後的回應」；而 Webhook 是訂閱系統事件的通知，屬於「系統發生事件後的主動推送」，不限於你發起的操作。兩者可以搭配使用，涵蓋不同的整合需求。