Webhook

概觀

使用者定義的 HTTP 回呼 (Webhook) 透過 ASoC REST API 支援。當 AppScan on Cloud 中發生事件時，Webhooks 會通知您。以下是支援的事件類型：

• 掃描執行完成
• 應用程式計數器或狀態已變更

若要使用 Webhook，先下載 AppScan Presence 並且將其安裝至您的本端網路（通常是一次性安裝）。Presence 連線至 ASoC。

當觸發 Webhook 時，Presence 會收到來自 ASoC 的指令，然後將 HTTP GET 要求傳送至您本端網路中的 Webhook URI。

由於 Presence 從您的網路中傳送要求，因此您可以通知內部伺服器，而無需為了來自 ASoC 的傳入要求而打開防火牆。

使用 REST API 建立和管理 Webhook

要建立、管理和配置 Webhook，請使用 ASoC REST API。Webhook 端點在公開API 參照中有說明：

AppScan REST API - Webhooks 端點

要建立 Webhook，請向 /api/v4/Webhooks 端點傳送附帶以下資訊的 POST 要求：

• PresenceId：處理 Webhook 要求的 AppScan Presence 實例的 ID
• Uri：觸發事件時，要呼叫的 HTTP 端點。URI 可以包括 {SubjectId} 保留元。
• 事件：觸發 Webhook 的事件類型 (ScanExecutionCompleted 或 ApplicationCountersChanged)
• 廣域：一佪布林值，用來表示這是廣域 Webhook（適用於所有應用程式或資產群組）或是限定範圍的 Webhook（僅適用於特定應用程式或資產群組）
• AssetGroupId：（選用）Webhook 適用的資產群組的 ID

範例：用於掃描完成的廣域 Webhook

此範例建立了一個廣域 Webhook，會在掃描執行完成時觸發。對於組織中的所有掃描，都會呼叫 Webhook：

{
    "PresenceId": "1234",
    "Uri": "http://mysite.com/ScanEnded/{SubjectId}",
    "Event": "ScanExecutionCompleted",
    "Global": true
    }

觸發此 Webhook 時，ASoC 會向您的服務傳送一個 GET 要求。{SubjectId} 值會被替換為該次掃描執行 ID：

GET /ScanEnded/9ea1fcb6-dc1d-443a-bfff-7465ced2ef1b HTTP/1.1 
    Host: mysite.com

重要事項：Webhook 不會傳送要求內文中的事件資料。若要擷取額外資料（例如在掃描中發現的問題清單），需要實作個別的服務，此服務會處理事件、使用 API 金鑰登入 ASoC，再從 ASoC API 擷取必要的資料。

Webhook URI 保留元

定義 Webhook URI 時，可以包括 {SubjectId} 保留元。此保留元會被替換為事件主題的 ID（通常為掃描執行 ID）。可以使用此值將基本事件上下文傳遞給 Ｗebhook 處理程式。

附帶保留元的例例 URI：

Webhook URI：http://myservice.com/ScanEnded/{SubjectId}

如果 ID 為 9ea1fcb6-dc1d-443a-bfff-7465ced2ef1b 的掃描執行完成，則會在以下位置呼叫 Ｗebhook：

http://mysite.com/ScanEnded/9ea1fcb6-dc1d-443a-bfff-7465ced2ef1b

Webhook 存取控制

要建立或修改 Webhook，您必須具有 ASoC 中的「建立 / 修改」Webhook 權限。預設情況下，此權限會指派給管理員和管理者角色，也可以將其新增到自訂角色。

您可以在組織層級或為特定資產群組定義 Webhook：

• 組織層次 Webhook 是由「管理員」定義及管理，或是由具有所有群組完整存取權的「使用者」定義及管理。
• 資產群組層次 Webhook 可以由具有資產群組存取權的「使用者」定義及管理，該使用者具有建立/修改 Webhook 的權限。

Webhook 範圍

您可以將 Ｗebhook 定義為廣域或限定範圍。

無論何時，每當在組織或資產群組中（取決於該 Webhook 定義在何處）發生與 Webhook 事件類型相符的事件，就會觸發廣域 Webhook。

不是「廣域」的 Webhook 可以與一或多個範圍相關聯。範圍可以是特定的應用程式，或者，如果該 Ｗebhook 是定義在組織層級，則可以是一個特定的資產群組。

限定範圍的 Webhook 只會在其中一個相關聯範圍內發生事件時觸發。

範例：如果 Webhook 在「掃描執行完成」時觸發，且該「範圍」是一個特定應用程式，Webhook 就會在每次該應用程式內的掃描執行完成時觸發。

為限定範圍的 Webhook 建立 Webhook 關聯

如果 Webhook 不是廣域的（也就是，如果設定了 "Global": false），則必須建立關聯以指定 Ｗebhook 適用的應用程式或資產群組。使用 Ｗebhook 關聯 API 端點建立這些關聯。

要將 Ｗebhook 與特定應用程式或資產群組建立關聯，請傳送一個 POST 要求至 /api/v4/Webhooks/Associations/{id} 端點，其中 {id} 為建立 Webhook 時回傳的 Webhook ID。

範例：特定資產群組的限定範圍 Webhook

首先，建立一個限定範圍 Webhook（非廣域）：

{
    "PresenceId": "1234",
    "Uri": "http://mysite.com/ScanEnded/{SubjectId}",
    "Event": "ScanExecutionCompleted",
    "Global": false,
    "AssetGroupId": "5678"
    }

在建立關聯之前，此 Webhook 不會觸發。接著，使用關聯端點將 Webhook 與特定應用程式建立關聯。如此可確保該 Webhook 僅會在該資產群組內的關聯應用程式進行掃描時觸發。

有關建立和管理 Webhook 關聯的詳細資訊，請參閱 AppScan REST API 說明文件。