核心功能
- 公開 API 端點，支援透過 HTTP POST 和 PUT 進行資料攝取，並採用現代身分驗證機制
- 基於使用者的速率限制和並行請求管理，並支援 CORS
- 採用 HMAC 簽章身分驗證以增強安全性，並支援自定義回應事件指令碼
- 提供範例請求範本，用於 XML Map 端口整合和工作流程自動化
概觀
Webhook 端口使資料能夠透過 HTTP POST 和 PUT 進入 知行之橋 工作流程。每個 Webhook 端口在應用程式中公開一個介面，外部用戶端可以向該介面傳送 XML 和 JSON 負載。這些負載將寫入輸出檔案，並傳送到工作流程中下一連線的端口。 可以在 Webhook 端口中指定範例請求，以簡化 POST 到端點的資料轉換流程。指定 XML 範例後，將 Webhook 端口連線到流程中的 XML Map 端口，XML Map 端口會自動檢測釋出到端點的 XML 檔案的預期結構。然後，可以使用 XML Map 端口的節點值編輯器將此結構對映到目標 XML 結構。端口配置
本節包含所有可配置的端口屬性。設定索引標籤
端口設定
與端口的核心操作相關的設定。進階設定
請求詳情索引標籤
提供一個 XML 或 JSON 範本，表示傳入資料的預期結構。指定範例請求的主要好處是將 Webhook 端口連線到工作流程中的 XML Map 端口。當 API 資料需要轉換為其他格式（例如 EDI 報文或資料庫插入）時，應使用 XML Map 端口。 XML Map 端口會檢測範例請求的 XML 結構，並將其用作 XML Map 端口的來源檔案。將代表目標格式的 XML 結構上傳為目的檔案，然後使用節點值編輯器將源結構轉換為目標結構。使用者索引標籤
使用者索引標籤可讓您：- 建立使用者及其關聯的 authtoken 和 OAuth 2.0 憑據
- 定義 POST 和/或 PUT 權限
- 指定每個使用者每小時可以發出多少個請求
- 指定允許多少個並行請求
此處的請求設定會覆蓋伺服器索引標籤的預設速率限制部分中的設定。
伺服器索引標籤
受信任的 IP 地址
預設速率限制／使用者
如果”使用者”索引標籤上未提供值，則限制允許的請求數量的設定。跨域資源共享 (CORS)
管理使用 CORS 來服務跨域資源的設定。| 設定 | 描述 |
|---|---|
| 啟用跨源資源共享 (CORS) | 是否啟用 CORS。僅當選中此框時，其餘選項才可用。 |
| 允許所有不帶 '*' 的域 | 如果啟用，域來源不限於特定清單。 |
| Access-Control-Allow-Origin | 要允許的以逗號分隔的域來源清單。作為 HTTP 回應訊息頭包含在內。 |
| Access-Control-Allow-Credentials | 跨域請求中是否允許使用者憑據（例如 cookie）。作為 HTTP 回應訊息頭包含在內。 |
| Access-Control-Allow-Methods | 允許的以逗號分隔的方法清單。作為 HTTP 回應訊息頭包含在內。 |
| Access-Control-Allow-Headers | 允許的訊息頭的逗號分隔清單。作為 HTTP 回應訊息頭包含在內。 |
| Access-Control-Max-Age | 可以快取 Access-Control 回應訊息頭值的最大持續時間（以秒為單位）。 |
進階設定
進階選項卡
訊息
訊息設定確定端口如何搜尋訊息並在處理後管理它們。
注意：以下設定已棄用，預設處於隱藏狀態。只有先前已啟用這些設定或將其配置為非預設值的端口才會顯示它們。若要保留成功處理的檔案副本，請在工作流程中右鍵單擊該端口，選擇顯示成功路徑，然後將成功路徑連線到 File 端口。
| 設定 | 描述 |
|---|---|
| 儲存到已傳送資料夾（已棄用） | 將端口處理的檔案複製到 Sent 資料夾。預設停用。儲存到 Sent 資料夾中的檔案不受靜態加密保護。 |
| 已傳送資料夾方案（已棄用） | 按所選時間間隔對 Sent 資料夾中的檔案進行分組。僅在啟用儲存到已傳送資料夾時適用。 |
日誌
用於管理日誌建立和儲存的設定。
| 設定 | 描述 |
|---|---|
| 日誌級別 | 指定要記錄在端口日誌目錄中的資訊型別：
|
| 日誌資料夾結構 | 指示端口根據選定的時間間隔將日誌資料夾中的檔案分組。例如，Weekly 選項指示端口每週建立一個新的子資料夾，並將該周的所有日誌儲存在該資料夾中。空白設定告訴端口將所有日誌直接儲存在日誌資料夾中。對於處理許多交易的端口，使用子資料夾有助於保持日誌的有序性並提高效能。 |
| 保留訊息副本 | 指示端口在日誌目錄中儲存最新訊息副本的切換。請注意，端口每個子資料夾只保留一個訊息，並且端口在再次執行時會覆蓋以前儲存的訊息。 |
其他
特殊設定適用於特定用例。
| 設定 | 描述 |
|---|---|
| 其他設定 | 允許在以分號分隔的清單中配置隱藏的端口設定，例如 setting1=value1;setting2=value2。正常的端口用例和功能不需要使用這些設定。 |
告警索引標籤
SLA 索引標籤
HMAC 身分驗證
HMAC（基於雜湊的訊息認證碼）簽章身分驗證是一種加密方法，用於驗證 Webhook 請求的真實性和完整性。它使用共享金鑰為每個請求生成唯一的簽章，從而確保：- 請求真實性：確認請求來自可信來源
- 資料完整性：驗證請求負載在傳輸過程中未被篡改
- 重放攻擊防護：防止攔截的請求被惡意重用
配置
- 啟用 HMAC 身分驗證
- 在 Webhook 端口設定中勾選啟用 HMAC 身分驗證。
- （可選）自定義 HMAC 簽章標頭值（預設值為
x-cdata-hmac-signature）。
為使用者設定 HMAC 金鑰
啟用 HMAC 身分驗證後：- 導航至 Webhook 端口的使用者索引標籤。
- 為每個授權的 Webhook 使用者配置 HMAC 金鑰：
- 系統會為每個使用者自動生成一個 HMAC 金鑰。您可以使用自定義值覆蓋自動生成的金鑰。每個使用者必須使用分配的 HMAC 金鑰為其 Webhook 請求生成有效的簽章。
Auth Token 身分驗證
使用者可以透過在請求中提供 authtoken 來存取 Webhook 資源。透過在使用者索引標籤上新增或編輯使用者並導航到身分驗證索引標籤來管理使用者和 authtoken。 在使用者呼叫 Webhook 介面之前，還必須設定連線的受信任 IP 地址。在伺服器索引標籤的受信任的 IP 地址部分中進行設定。預設情況下，所有 IP 地址均受限制。在基本身分驗證中使用身分驗證權杖
使用基本身分驗證時，應將使用者的 authtoken 用作密碼。在 HTTP 標頭中使用認證權杖
將 HTTP 標頭x-{companyName}-authtoken 與 authtoken 一起新增為 HTTP 請求的一部分。
使用身分驗證權杖作為查詢字串參數
要允許端口在查詢字串參數中傳遞 authtoken，請在伺服器索引標籤的進階設定部分中勾選 Allow authtoken in URL。 啟用此功能後，可以將 authtoken 指定為@authtoken 參數的值，該參數可以作為 HTTP 表單資料或查詢參數的一部分提供。
OAuth 2.0 身分驗證
使用者可以使用 OAuth 2.0 身分驗證來保護 Webhook 資源。透過在使用者索引標籤上新增或編輯使用者並導航到身分驗證索引標籤來管理使用者和 OAuth 憑據。接收資料
將資料上傳到 Webhook 介面時，Web 請求的主體將作為輸出檔案寫入並傳送到工作流程中下一個連線的端口。這允許使用靈活的方法透過呼叫外部 API 來呼叫 知行之橋 工作流程。自定義回應
通常，Webhook 端口接受帶有請求已接受的權杖回應的釋出資料，但可以使用Response 事件自定義回應，其中 _request、_httpheaders、_response 和 _message 特殊專案可用。指定後，端口期望透過 _response 項提供自定義回應。
您還可以使用 Response 事件，透過以下屬性推送自定義輸出項：
- Filename：傳遞到下游工作流程的輸出訊息檔名。
- Data：包含在傳遞到下游工作流程的訊息中的資料。對於二進位資料，請改用 Base64Data 屬性。
- Base64Data：包含在傳遞到下游工作流程的訊息中的 Base64 編碼資料。
- HeaderNames#：包含在傳遞到下游工作流程的訊息中的標頭名稱清單。使用 HeaderValues 屬性在匹配的索引處指定這些標頭的值。
- HeaderValues#：包含在傳遞到下游工作流程的訊息中的標頭值清單。這些值用於 HeaderNames 清單中相同索引處定義的標頭名稱。
- Logs#：包含在交易日誌中的日誌項目清單。
範例
若要將包含 Webhook 請求正文的檔案（帶有自定義檔名和標頭）推送到下游工作流程中，Response 事件中的 ArcScript 可能如下所示：
Response 事件中的 ArcScript 可能如下所示：
Response 事件，用戶端可以傳送類似於以下內容的請求：