Webhook

Webhook 是託管商業邏輯或呼叫其他服務的服務。在工作階段期間，Webhook 可讓您使用 Dialogflow CX 自然語言處理功能擷取的資料，生成動態回覆、驗證收集到的資料，或在後端觸發動作。

Webhook 可以是標準 Webhook 或彈性 Webhook。使用標準 Webhook 時，要求和回應欄位是由 Dialogflow CX 定義。使用彈性 Webhook 時，您需要定義要求和回應欄位。

您也可以使用 $request.webhook_status_code 要求參數，存取 Webhook 呼叫的 HTTP 狀態碼。

標準 Webhook

使用標準 Webhook 時，您會使用 Dialogflow CX 定義的要求和回應訊息。要求訊息會提供許多工作階段詳細資料。例如，目前有效的頁面、最近比對成功的意圖、工作階段參數值，以及代理定義的回覆，都會包含在內。

標準 Webhook 要求

呼叫含有 Webhook 的執行要求時，Dialogflow CX 會將 HTTPS POST Webhook 要求傳送至 Webhook 服務。這項要求的內文是 WebhookRequest JSON 物件，內含工作階段相關資訊。

部分整合項目會在 WebhookRequest.payload 欄位中填入額外資訊。例如，Dialogflow CX 電話閘道整合會提供使用者來電號碼。

詳情請參閱 WebhookRequest (V3) 或 WebhookRequest (V3Beta1) 參考文件。

標準 Webhook 回應

Webhook 服務收到要求後，必須傳送符合下列規定的回應：

詳情請參閱 WebhookResponse (V3) 或 WebhookResponse (V3Beta1) 參考文件。

標準 Webhook 資源設定

下表說明標準 Webhook 的 Webhook 資源設定：

X 項目
顯示名稱 控制台中顯示的 Webhook 名稱。
Webhook 逾時 Dialogflow CX 向 Webhook 服務傳送 HTTP 要求時，這項設定會控制每次要求嘗試的逾時時間 (以秒為單位)，而非整個對話回合。如果嘗試逾時或因暫時性錯誤而失敗，Dialogflow CX 會自動重試一次。這項重試作業可能會導致總處理時間達到設定逾時值的兩倍，然後才會傳回錯誤。如果重試後仍逾時，Dialogflow CX 會叫用 webhook.error.timeout 事件。詳情請參閱「自動重試」。
類型 如果您使用 Service Directory 存取私人網路，請設為「Service Directory」，否則請設為「一般網路服務」。
Webhook 網址 提供 Webhook 服務的網址。
子類型 設為「Standard」。
特定環境的 Webhook 您可以提供環境專屬的 Webhook。
驗證 請參閱「驗證」一節。
自訂 CA 憑證 用於上傳自訂 CA 憑證。

彈性 Webhook

您可以透過彈性 Webhook 定義要求 HTTP 方法、要求網址參數，以及要求和回應訊息的欄位。要求只能提供所選參數值，回應則只能提供參數覆寫值。這可簡化代理與 Webhook 之間的介面，因為除了工作階段參數值之外，幾乎不需要傳達任何其他內容。此外，要求和回應訊息只會包含所需內容，您也可以為各種情境提供專屬的 Webhook 訊息，因此能簡化 Webhook 實作。

彈性 Webhook 要求

為代理建立 Webhook 資源時，您可以為 Webhook 要求指定下列項目：

  • 傳送至 Webhook 服務的 Webhook 要求所使用的 HTTP 方法。
  • Dialogflow CX 應使用網址傳送至 Webhook 服務的工作階段參數值。
  • 如果您選擇 POST、PUT 或 PATCH 做為方法，Dialogflow CX 應透過要求 JSON 主體傳送至 Webhook 服務的工作階段參數值。

如要使用要求網址或 JSON 主體傳送工作階段參數值，請使用參數參照。您不需要對參數參照進行網址逸出處理，也不必加上引號。在執行階段，Dialogflow CX 會視需要對參數值進行網址逸出。清單或複合值會以 JSON 格式提供。

在 JSON 主體中使用參數參照時，無論參數類型為何，都必須用引號括住參照。如果參數實際上是數值純量、清單或複合值，Dialogflow CX 會在執行階段傳送要求時移除引號，以保留參數資料類型。字串純量類型仍會加上引號。如果在字串值中參照數值純量、清單或複合值 (例如：「This is a number: $session.params.size」)，系統會將參數視為字串 (「This is a number: 3」)。

舉例來說，您可以將 fruit 和 size 工作階段參數值提供給要求網址，如下所示：

https://your-webhook-service.com/handler?f=$session.params.fruit&s=$session.params.size

並在要求 JSON 主體中加入下列內容：

{
  "fruitParameter": "$session.params.fruit",
  "sizeParameter": "$session.params.size"
}

彈性 Webhook 回應

為代理建立 Webhook 資源時，您可以指定 Dialogflow CX 在執行階段應設為 Webhook 回應特定欄位的會話參數。

回覆必須符合下列限制：

  • 回應必須在建立 Webhook 資源時設定的逾時時間內發生，否則要求會逾時。
  • 回應大小不得超過 64 KiB。

如要指定純量、清單或複合欄位，請使用下列格式：

$.fully.qualified.path.to.field

以下列 JSON 回應為例：

{
  "routes" : [
    {
      "legs" : [
        {
          "distance" : {
            "text" : "2,064 mi",
            "value" : 3321004
          }
        }
      ]
    }
  ]
}

如要指定「value」欄位，請使用下列程式碼：

$.routes[0].legs[0].distance.value

彈性 Webhook 資源設定

下表說明彈性 Webhook 的 Webhook 資源設定。

X 項目
顯示名稱 控制台中顯示的 Webhook 名稱。
Webhook 逾時 Dialogflow CX 向 Webhook 服務傳送 HTTP 要求時，這項設定會控制每次要求嘗試的逾時時間 (以秒為單位)，而非整個對話回合。如果嘗試逾時或因暫時性錯誤而失敗，Dialogflow CX 會自動重試一次。這項重試作業可能會導致總處理時間達到設定逾時值的兩倍，然後才會傳回錯誤。如果重試後仍逾時，Dialogflow CX 會叫用 webhook.error.timeout 事件。詳情請參閱「自動重試」。
類型 如果您使用 Service Directory 存取私人網路，請設為「Service Directory」，否則請設為「一般網路服務」。
Webhook 網址 提供 Webhook 服務的網址，其中可能包含工作階段參數的參照。
子類型 設為「彈性」。
方法 設定 Webhook 要求的 HTTP 方法。
要求主體 按照上述說明提供要求 JSON 主體。
回覆設定 提供應設為回覆欄位的對話階段參數，如上所述。
特定環境的 Webhook 您可以提供環境專屬 Webhook
驗證 請參閱驗證一節。
自訂 CA 憑證 用於上傳自訂 CA 憑證。

使用預先定義的自訂範本

Dialogflow 提供預先定義的自訂範本，可讓您將彈性的 Webhook 與 Salesforce CRM 整合。

  1. 前往「Manage」分頁，選取「Webhooks」，然後點選「Create」。
  2. 在「Subtype」(子類型) 下方，選取「Flexible」(彈性)。
  3. 按一下「使用預先定義的範本設定」。
  4. 在「Integration type」(整合類型) 選單中，選取「Salesforce」。
  5. 在「API name」(API 名稱) 選單中，選取 API 名稱。範本會根據您選擇的 API 名稱，自動填寫 Webhook 表單。
    1. 根據參數，手動設定下列欄位 (如適用)：
      • Webhook 網址
      • 方法
      • 要求主體 JSON
      • 回覆設定
    2. 「Authentication」(驗證) 部分會醒目顯示必要的 OAuth 欄位。
  6. 按一下 [儲存]。

Webhook 服務需求

Webhook 服務必須符合下列規定：

驗證

請保護 Webhook 服務，確保只有您或 Dialogflow CX 代理可以提出要求。建立或編輯 Webhook 資源時，請設定這項屬性。Dialogflow CX 支援下列驗證機制：

X 項目
驗證標頭 在 Webhook 設定中，您可以指定選用的 HTTP 標頭鍵/值組合。如果提供，Dialogflow CX 會將這些 HTTP 標頭新增至 Webhook 要求。通常會提供一組鍵為 authorization 的配對。標頭值支援工作階段參數參照和系統函式剖析，就像靜態回覆訊息一樣。如果您使用靜態憑證做為 authorization 標頭，建議您使用 Secret Manager 提供憑證。
使用使用者名稱和密碼的基本驗證 在 Webhook 設定中，您可以指定選用的登入使用者名稱和密碼值。如果提供，Dialogflow CX 會在 Webhook 要求中加入授權 HTTP 標頭。這個標頭的格式為："authorization: Basic <base 64 encoding of the string username:password>"。建議您使用 Secret Manager 提供使用者名稱和密碼。
第三方 OAuth 您可以指定第三方 OAuth 設定，讓 Dialogflow CX 從 OAuth 系統交換存取權杖，並將其新增至授權 HTTP 標頭。僅支援用戶端憑證流程。建議您使用 Secret Manager 提供用戶端密鑰。
服務代理存取權杖 已停售。
服務帳戶 您可以使用服務帳戶進行驗證。可用於存取其他 Google Cloud API。
服務代理 ID 權杖 您可以在「服務代理驗證」部分選擇「ID 權杖」，使用服務代理 ID 權杖進行驗證。這樣就能存取 Cloud Run 資源。
雙向傳輸層安全標準 (TLS) 驗證 請參閱雙向 TLS 驗證說明文件。

第三方 OAuth

Dialogflow CX 會從第三方 OAuth 供應商收集存取權杖，並在提出 Webhook 要求時，將權杖新增至授權 HTTP 標頭。

下表說明第三方 OAuth 的資源設定：

X 項目
用戶端 ID 要求 OAuth 權杖時要使用的用戶端 ID。
用戶端密鑰 要求 OAuth 權杖時要使用的密鑰。建議您使用 Secret Manager 提供用戶端密鑰。
OAuth 端點網址 用來要求 OAuth 權杖的網址。
OAuth 範圍 以半形逗號分隔的清單，列出 OAuth 權杖可使用的範圍。

傳送至 OAuth 端點網址以接收權杖的要求，不含為 Webhook 要求設定的自訂要求標頭。您可以將自訂資訊做為 OAuth 端點網址查詢字串中的參數，傳遞至 OAuth 伺服器。

服務代理程式 ID 權杖

Dialogflow CX 可使用 Dialogflow CX 服務代理產生 ID 權杖。Dialogflow CX 呼叫 Webhook 時，會將這個權杖新增至 Authorization HTTP 標頭。

將 Cloud Run 叫用者角色 (roles/run.invoker) 授予

service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
 如果 Cloud Run 資源位於同一個資源專案，您不需額外的 Identity and Access Management (IAM) 權限即可呼叫這些資源。

用於產生 ID 權杖的目標對象是整個 Webhook 網址，不含任何查詢參數。如果您使用 Cloud Run，請確認 Cloud Run 目標對象支援這個網址。

舉例來說，如果 Webhook 網址為：

https://myproject.cloudfunctions.net/my-function/method1?query=value

自訂目標對象中必須包含下列網址：

https://myproject.cloudfunctions.net/my-function/method1

任何 Webhook 也可以選擇使用 Google 用戶端程式庫或開放原始碼程式庫 (例如 Node.js 的 Google Auth 程式庫) 驗證權杖。

如果 Webhook 託管於 Cloud Run，且透過負載平衡器存取，請將負載平衡器的網址新增為 Cloud Run 的自訂目標對象。如要進一步瞭解自訂目標對象，請參閱「為服務設定自訂目標對象」。

服務帳戶

服務帳戶可用於驗證對任何支援 Google API 的 Webhook 要求。

如果您還沒有服務帳戶，請建立一個。

服務帳戶是主體，因此只要授予角色，就能像其他主體一樣存取專案中的資源。服務帳戶電子郵件會用於產生存取權杖，並在 Webhook 要求的 Authorization 標頭中傳送。

如要設定 Webhook 使用服務帳戶，您必須具備下列權限：

  • roles/iam.serviceAccountUser

如要產生權杖，Dialogflow 服務代理必須具備下列權限：

  • roles/iam.serviceAccountTokenCreator

服務帳戶也必須具備權限，才能存取託管 Webhook 的服務。

Secret Manager 驗證

如果您使用驗證標頭、使用者名稱和密碼的基本驗證，或第三方 OAuth，可以使用 Secret Manager 將憑證儲存為 Secret。以下是使用 Secret 驗證 Webhook 的必要步驟：

  1. 如果沒有 Secret，請建立 Secret。
  2. 將新密鑰的 Secret Manager 密鑰存取者 (roles/secretmanager.secretAccessor) 角色授予 Dialogflow 服務代理。
  3. 將憑證複製到剪貼簿。
  4. 在密鑰中新增密鑰版本，並貼上憑證做為密鑰值：
    • 如果使用驗證標頭，請輸入 Bearer <YOUR_CREDENTIAL>。
    • 如果使用基本使用者名稱和密碼驗證，請輸入 <YOUR_USERNAME>:<YOUR_PASSWORD>。
    • 請省略結尾的任何換行字元。
  5. 複製您新增的密鑰版本名稱。名稱格式為 projects/<var>PROJECT_ID</var>/secrets/<var>SECRET_ID</var>/versions/<var>VERSION_ID</var>。
  6. 開啟 Webhook 編輯畫面。
  7. 設定驗證機制：
    • 如果您使用驗證標頭，請建立新的密鑰版本要求標頭。在「Key」(金鑰) 欄位中輸入「Authorization」，然後將密鑰版本名稱貼到「Secret version」(密鑰版本) 欄位。
    • 如要進行基本使用者名稱和密碼驗證，請按一下「Basic Auth」(基本驗證) 下方的「Secret version」(密鑰版本)，然後將密鑰版本名稱貼到「Secret version」(密鑰版本) 欄位中。
    • 如果使用「Third-party OAuth」(第三方 OAuth)，請按一下「Third-party OAuth」(第三方 OAuth) 下方的「Secret version」(密鑰版本)，然後將密鑰版本名稱貼到「Secret version」(密鑰版本) 欄位。
  8. 按一下 [儲存]。

HTTPS 憑證驗證

Dialogflow CX 預設會使用 Google 的預設信任存放區驗證 HTTPS 憑證。如果您打算在 HTTPS 伺服器使用 Google 預設信任存放區無法辨識的憑證，例如自行簽署的憑證或自訂根憑證，請參閱「自訂 CA 憑證」。

特定環境的 Webhook

如果您使用環境區隔正式環境和開發環境，可以將 Webhook 設為環境專屬。您可以為每個 Webhook 資源提供環境專屬的網址和驗證設定。

這項設定可讓您安全地開發及測試 Webhook 程式碼更新，再部署至正式環境。

建立或編輯 Webhook 資源

Webhook 服務執行後，請在代理中建立 Webhook 資源，其中包含連線和驗證資訊。您隨時可以編輯 Webhook 資源設定。

如要建立或編輯 Webhook 資源，請按照下列步驟操作：

控制台

  1. 開啟 Dialogflow CX 控制台。
  2. 前往專案。
  3. 選取代理程式。
  4. 按一下「管理」分頁標籤。
  5. 按一下「Webhooks」。
  6. 按一下「建立」，或選取要編輯的現有 Webhook。
  7. 設定標準 Webhook 資源設定或彈性 Webhook 資源設定。
  8. 按一下 [儲存]。

API

如要瞭解如何建立 Webhook 資源，請參閱 Webhook 類型的 Webhook 方法。create如要瞭解如何編輯 Webhook 資源 (環境專屬設定除外)，請參閱 Webhook 類型的 patch 或 update 方法。

選取 Webhook 參照的通訊協定和版本：

通訊協定 V3 V3beta1
REST Webhook 資源 Webhook 資源
RPC Webhook 介面 Webhook 介面
C++ WebhooksClient 不適用
C# WebhooksClient 不適用
Go WebhooksClient 不適用
Java WebhooksClient WebhooksClient
Node.js WebhooksClient WebhooksClient
PHP 不適用 不適用
Python WebhooksClient WebhooksClient
小茹 不適用 不適用

如要瞭解如何編輯 Webhook 的環境專屬設定，請參閱 Environment 類型的 patch 或 update 方法。

選取環境參照的通訊協定和版本：

通訊協定 V3 V3beta1
REST 環境資源 環境資源
RPC 環境介面 環境介面
C++ EnvironmentsClient 不適用
C# EnvironmentsClient 不適用
Go EnvironmentsClient 不適用
Java EnvironmentsClient EnvironmentsClient
Node.js EnvironmentsClient EnvironmentsClient
PHP 不適用 不適用
Python EnvironmentsClient EnvironmentsClient
小茹 不適用 不適用

Webhook 錯誤

如果 Webhook 服務在處理 Webhook 要求時發生錯誤，Webhook 程式碼應傳回下列其中一個 HTTP 狀態碼：

  • 400：要求無效
  • 401：未經授權
  • 403：禁止存取
  • 404：找不到
  • 500：伺服器故障
  • 503：無法使用服務

在下列錯誤情況下，Dialogflow CX 會叫用 Webhook 錯誤或逾時內建事件，並照常繼續處理：

  • 超過回應逾時時間。
  • 收到錯誤狀態碼。
  • 回覆無效。
  • 無法使用 Webhook 服務。

如果 Webhook 服務呼叫是由意圖偵測 API 呼叫觸發，意圖偵測回應中的 queryResult.webhookStatuses 欄位會包含 Webhook 狀態資訊。

自動重試

Dialogflow CX 會在發生特定 Webhook 錯誤時自動重試要求，提升穩定性。自動重試功能預設為啟用，且無法停用。

Dialogflow CX 會針對暫時性失敗執行一次重試，例如要求逾時、網路連線中斷，以及 5xx 範圍內的 HTTP 狀態碼 (例如 500 Server fault 或 503 Service unavailable)。終端用戶端錯誤 (例如 HTTP 狀態碼 404 Not found) 會立即失敗，不會重試。

累計延遲時間和逾時預算

由於 Dialogflow CX 會重試暫時性失敗一次，因此在 Dialogflow CX 傳回錯誤之前，無回應的 Webhook 端點可能會導致累積處理時間最多達到設定逾時值的兩倍。舉例來說，如果採用預設的 5 秒逾時設定，沒有回應的端點會在首次嘗試 5 秒後逾時，並在重試 5 秒後再次逾時。因此，Dialogflow CX 叫用錯誤處理常式 (例如 webhook.error.timeout 事件處理常式或 sys.no-match-default 事件處理常式) 之前的總延遲時間約為 10 秒。

如果架構有嚴格的上游延遲限制 (例如電話或互動式語音應答 (IVR) 系統在 10 秒逾時視窗後終止通話)，請將 Webhook 逾時設為允許視窗的一半 (例如 2.5 到 4 秒之間)，為兩次嘗試預留時間。

重試的最佳做法

如要在 Webhook 服務中有效處理重試作業，請按照下列步驟操作：

  • 在 Webhook 服務邏輯中導入冪等性或要求簡化功能，安全地處理重複要求。
  • 如果 Webhook 作業時間超過設定的逾時時間，請立即傳回 HTTP 狀態碼 200 OK 回應和備用訊息，並以非同步方式處理長時間執行的工作。

使用 Cloud Run

Dialogflow CX 與 Cloud Run 整合，可讓您建立安全的無伺服器 Webhook。如果您建立的 Cloud Run 資源與代理位於同一個專案，請選取「Service Agent Auth」(服務代理驗證)，然後在驗證設定中選取「ID token」(ID 權杖)，讓代理能安全呼叫 Webhook。

在下列兩種情況下，您必須手動設定這項整合：

  1. 虛擬服務專員專案必須具備 Dialogflow CX 服務代理 服務帳戶，且位址如下：
    service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
     當您為專案建立第一個代理時，系統通常會自動建立這個特殊服務帳戶和相關聯的金鑰。如果代理是在 2020 年 11 月 1 日前建立，您可以觸發建立這個特殊服務帳戶：
    1. 為專案建立新的代理。
    2. 執行下列指令： 
      gcloud beta services identity create --service=dialogflow.googleapis.com --project=agent-project-id
  2. 如果 Webhook 函式與代理程式位於不同專案，您必須將 Cloud Run 叫用者或 Cloud Functions 叫用者 IAM 角色授予 Cloud Run 資源專案中的 Dialogflow CX 服務代理服務帳戶。

接著，在「Auth configuration」(驗證設定) 部分，依序選取「Service Agent Auth」(服務代理驗證) >「ID Token」(ID 權杖)。

使用容器化 Webhook 和 Go ezcx 框架

如要使用 Go 實作容器化 Webhook，請參閱 Go ezcx 架構。這個架構可簡化建立 Webhook 所需的許多步驟。

搭配使用 Cloud Run 與僅限內部的流量

如果代理位於相同專案或相同 VPC Service Controls 範圍，您可以使用 Cloud Run 資源，並設定為接受來自相同專案或相同 VPC Service Controls 範圍內虛擬私有雲 (VPC) 網路的內部流量，做為 Webhook。

使用 Service Directory 存取私人網路

Dialogflow CX 與 Service Directory 私人網路存取權整合，因此可連線至虛擬私有雲網路中的 Webhook 目標。這樣一來，流量就會保留在 Google Cloud 網路中，並強制執行 IAM 和 VPC Service Controls。

如要設定指定私人網路的 Webhook，請按照下列步驟操作：

  1. 按照「Service Directory 私人網路設定」一文的指示，設定虛擬私有雲網路和 Service Directory 端點。

  2. 代理專案必須具備 Dialogflow CX 服務代理 服務帳戶，且位址如下：

    service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com

    在 Service Directory 所在的專案中，將下列角色授予 Dialogflow CX 服務代理服務帳戶：

    • servicedirectory.viewer
    • servicedirectory.pscAuthorizedService

    此外，如果 Service Directory 與 Dialogflow CX 代理位於不同專案，您也必須將 servicedirectory.viewer 角色授予 Dialogflow CX 代理所在專案中的 Dialogflow CX 服務代理帳戶。

  3. 建立 Webhook 時，請指定 Service Directory 服務、網址和任何選用的驗證資訊。

    控制台

    Service Directory Webhook 螢幕截圖。

    API

    請參閱 Webhook 類型的 Webhook 欄位。 serviceDirectory

    選取 Webhook 參照的通訊協定和版本：

    通訊協定 V3 V3beta1
    REST Webhook 資源 Webhook 資源
    RPC Webhook 介面 Webhook 介面
    C++ WebhooksClient 不適用
    C# WebhooksClient 不適用
    Go WebhooksClient 不適用
    Java WebhooksClient WebhooksClient
    Node.js WebhooksClient WebhooksClient
    PHP 不適用 不適用
    Python WebhooksClient WebhooksClient
    小茹 不適用 不適用

如要排解問題，您可以設定私人運作時間檢查，確認 Service Directory 設定正確無誤。

範例和疑難排解

詳情請參閱 Webhook 使用指南。

上一頁
執行要求
下一頁
發電機