文件中心 Webhook 事件¶

當你訂閱了文件中心相關的 Webhook 事件後，U-Office Force X 會在文件異動時，以 HTTP POST 方式將事件資料推送至你設定的接收端 URL。本文說明你的接收端會收到的 JSON 資料格式，幫助你正確解析與處理通知內容。

通用說明¶

請求方式¶

所有事件通知皆以 HTTP POST 發送，Request Body 為 JSON 格式：

POST https://{your-receiving-endpoint}
Content-Type: application/json

回應要求¶

你的接收端在成功處理後，應回傳 HTTP 200 OK。若未在時間內回應，系統將依重試策略重新發送通知。

簽章驗證¶

每次推送都會包含簽章資訊於 HTTP Header 中，你可以使用建立 Webhook 通道時取得的 Secret (HMAC) 來驗證請求是否確實來自 U-Office Force X，以防止偽造請求。唯「驗證 webhook URL 是否可連通」這個操作不帶簽章。

X-Webhook-Signature: sha256=4f2a8c1a8c27d6fcb5d74be9f6b7f3d3c7d89a66c16d4a50e5a2d7e0d8f1a234

事件類型¶

以下列出文件中心支援的 Webhook 事件類型：

AddFile：當有新文件被新增至文件中心時觸發
ObsoleteFile：作廢文件
DeleteFile：刪除文件
RenameFile：重新命名文件
UpdateVersion：更新文件版本
UpdateProperty：更新文件屬性
MoveFolder：搬移目錄
RenameFolder：重新命名目錄

JSON 資料格式¶

所有 Webhook 事件推送的 JSON 皆包含共用欄位與事件特定欄位兩大類型。共用欄位提供了事件的基本資訊，而事件特定欄位則根據不同事件類型提供了相關的詳細資料。

共用欄位¶

所有文件中心事件推送的 JSON 皆包含以下共用欄位：

id：事件的唯一識別碼
type：事件類型，例如 dms.folder.files.changed
timestamp：事件發生的時間戳記，格式為 ISO 8601
version：事件資料的版本號
source：事件來源資訊，包含 corpId、channelType、channelId 等欄位
data：事件特定欄位資訊，根據不同事件類型包含不同的詳細資料

{
  "id": "evt-20260324-0001",
  "type": "dms.folder.files.changed",
  "timestamp": "2026-03-24T14:32:10+08:00",
  "version": "1.0",
  "source": {
    "corpId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "channelType": "system",
    "channelId": "9a5d6d26-8d31-4bde-a8fa-5c8c3c6b41af"
  },
  "data": {事件特定欄位資訊}
}

DMS 事件資料範例¶

data 欄位的內容會根據事件類型而有所不同，以下是一個當有新文件被新增至文件中心時觸發的 dms.folder.files.changed 事件的範例：

path：文件所在的目錄路徑
folderId：文件所屬上層的目錄 ID(搠源至設定會發送webhook通知的目錄，因此不一定是文件的直接上層目錄)
action：事件動作類型，例如 AddFile、DeleteFile 等
file：文件相關資訊，包含 id、fileName、length、contentType、downloadUrl 等欄位
creator：文件建立者資訊，包含 account、name、department 等欄位
docProperty：管制文件專屬資訊，包含 name、docSerial、docVersion、publishDept、applyDept、startTime、endTime、summary、memo 等欄位

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "type": "dms.folder.files.changed",
  "timestamp": "2026-03-24T15:00:00+08:00",
  "version": "1.0",
  "source": {
    "corpId": "550e8400-e29b-41d4-a716-446655440000",
    "channelType": "system",
    "channelId": "4b1d8c59-e84d-4b85-93c9-2d95f2780b62"
  },
  "data": {
    "path": "研發文件/產品A/規格書",
    "folderId": "f7dd1d3d-7e83-49b1-b6de-5f6b2f3f42c1",
    "action": "UpdateVersion",
    "file": {
      "id": "3c11dd75-9e88-4b45-90a0-4c0de7df19a1",
      "fileName": "ProductA-Spec-v2.1.pdf",
      "length": 1843200,
      "contentType": "application/pdf",
      "downloadUrl": "https://example.com/files/ProductA-Spec-v2.1.pdf"
    },
    "creator": {
      "account": "u00123",
      "name": "王小明",
      "department": "研發部"
    },
    "docProperty": {
      "name": "文件管制作業程序",
      "docSerial": "RD-PRODA-001",
      "docVersion": "V2.1",
      "publishDept": "研發部",
      "applyDept": "研發部, 品保部",
      "startTime": "2026-03-24",
      "endTime": null,
      "summary": "更新產品 A 規格內容與版本資訊",
      "memo": "修正第 3 章接口定義"
    }
  }
}