Webhook

Webhook 是代管商業邏輯或呼叫其他服務的服務。 在工作階段期間，您可以透過 Webhook 使用 Dialogflow CX 自然語言處理程序擷取的資料，產生動態回應、驗證收集到的資料，或在後端觸發動作。

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

標準 Webhook

使用標準 Webhook 時，您會使用 Dialogflow CX 定義的要求和回應訊息。要求訊息會提供工作階段的許多詳細資料。 例如，目前啟用的網頁、最近相符的意圖、工作階段參數值，以及代理程式定義的回應都會納入。

標準 Webhook 要求

當系統呼叫含有 Webhook 的「執行要求」時，Dialogflow CX 會向您的 Webhook 服務傳送 HTTPS POST Webhook 要求。這項要求的主體是 WebhookRequestJSON 物件，內含工作階段相關資訊。

部分整合會在 WebhookRequest.payload 欄位中填入額外資訊。舉例來說，Dialogflow CX Phone Gateway 整合會提供來電者的使用者 ID。

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

標準 Webhook 回應

Webhook 服務收到 Webhook 要求後，必須傳送 Webhook 回應。回覆內容有以下限制：

• 回應必須在您建立 Webhook 資源時設定的逾時時間內發生，否則要求將會逾時。
• 回應大小必須小於或等於 64 KiB。

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

標準 Webhook 資源設定

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

字詞	定義
顯示名稱	Webhook 在控制台中顯示的名稱。
Webhook 逾時	Dialogflow CX 將 Webhook 要求傳送至 Webhook 服務時，可能會在等待回應時逾時。這項設定可控制逾時時間 (以秒為單位)。如果發生逾時，Dialogflow CX 會叫用 webhook.error.timeout 事件。
類型	如果您使用 Service Directory 存取私人網路，請設為「Service Directory」，否則請設為「Generic web service」。
Webhook 網址	提供 Webhook 服務的網址。
子類型	設為「標準」
特定環境的 Webhook	您可以提供環境專屬的 Webhook。
驗證	請參閱驗證部分。
自訂 CA 憑證	用於上傳自訂 CA 憑證。

彈性 Webhook

使用彈性 Webhook 時，您可以定義要求 HTTP 方法、要求 URL 參數，以及要求和回應訊息的欄位。要求只能提供所選參數值，回應也只能提供參數覆寫值。這項限制其實很有幫助，因為它簡化了代理與 Webhook 之間的介面。代理程式和 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 資源設定：

字詞	定義
顯示名稱	Webhook 在控制台中顯示的名稱。
Webhook 逾時	Dialogflow CX 將 Webhook 要求傳送至 Webhook 服務時，可能會在等待回應時逾時。這項設定會控管逾時時間 (以秒為單位)。如果發生逾時，Dialogflow CX 會叫用 webhook.error.timeout 事件。
類型	如果您使用 Service Directory 進行私人網路存取，請設為「Service Directory」，否則請設為「Generic web service」。
Webhook 網址	提供 Webhook 服務的網址，其中可能包含工作階段參數的參照。
子類型	設為「彈性」
方法	設定 Webhook 要求的 HTTP 方法。
要求主體	按照上述說明提供 JSON 要求主體。
回覆設定	提供應設為回應欄位的會期參數，如上所述。
特定環境的 Webhook	您可以提供環境專屬的 Webhook。
驗證	請參閱驗證部分。
自訂 CA 憑證	用於上傳自訂 CA 憑證。

使用預先定義的自訂範本

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

1. 在「管理」分頁下方，依序點選「Webhook」和「+ 建立」。

2. 在「Subtype」(子類型) 下方，選取「Flexible」(彈性)。

3. 按一下「使用預先定義的範本設定」，即可啟用這項功能。

4. 在「整合類型」下拉式選單中，選取「Salesforce」。

5. 在「API 名稱」下拉式選單中，選取 API 名稱。範本會根據您選擇的 API 名稱，自動填寫 Webhook 表單。

   1. 視情況而定，您可以根據參數手動設定下列欄位：

      • Webhook 網址
      • 方法
      • 要求主體 JSON
      • 回覆設定

   2. 「驗證」部分會醒目顯示必要的 OAuth 欄位。

6. 按一下「儲存」即可建立 Webhook。

Webhook 服務規定

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

• 必須處理 HTTPS 要求。系統不支援 HTTP。 如果您使用 Compute 或無伺服器運算解決方案，在 Google Cloud Platform 上代管 Webhook 服務，請參閱產品說明文件，瞭解如何透過 HTTPS 提供服務。如需其他代管選項，請參閱「取得網域的安全資料傳輸層 (SSL) 憑證」。
• 除非是託管為 Cloud Run 資源，或是以 Service Directory 網頁掛鉤的形式存取，否則要求網址必須可公開存取。
• 必須按照標準 Webhook 或彈性 Webhook 專區的說明處理要求和回應。
• 如果您的代理程式未與服務目錄私人網路存取權整合，啟用 VPC Service Controls 時，系統會將 Webhook 呼叫視為超出服務範圍，並加以封鎖。Service Directory 支援的端點有限，詳情請參閱「Service Directory」。

驗證

請務必保護 Webhook 服務安全，確保只有您或 Dialogflow CX 虛擬服務專員有權提出要求。您可以在建立或編輯 Webhook 資源時設定這項屬性。 Dialogflow CX 支援下列驗證機制：

字詞	定義
驗證標頭	如要設定 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、服務代理程式驗證。

注意： 我們不建議使用 IP 範圍驗證 Webhook 要求。如果您選擇使用要求的來源 IP 啟用網路周邊連線，請允許來自 https://www.gstatic.com/ipranges/goog.json 所列範圍的要求，然後拒絕來自 https://www.gstatic.com/ipranges/cloud.json 所列範圍的任何連線 (這些是可用於部署第三方工作負載的 Google 位址)。此外，Dialogflow 無法保證傳送 Webhook 要求的機器的 IP 範圍。

注意： 2025 年 8 月 15 日後，匯出的代理程式將不再包含驗證標頭的原始值憑證、使用使用者名稱和密碼的基本驗證，以及第三方 OAuth。

第三方 OAuth

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

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

字詞	定義
用戶端 ID	要求 OAuth 權杖時要使用的用戶端 ID。
用戶端密鑰	要求 OAuth 權杖時使用的密鑰。建議您使用 Secret Manager 提供用戶端密鑰。
OAuth 端點網址	用來要求 OAuth 權杖的網址。
OAuth 範圍	以逗號分隔的範圍清單，OAuth 權杖可用於這些範圍。

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

注意： 只要要求是在同一個 Dialogflow CX 伺服器上提出，且權杖尚未過期，使用相同用戶端 ID、端點網址和範圍的 Webhook 要求就會重複使用第三方 OAuth 權杖。為實現高可用性，代理程式會部署在許多不共用 OAuth 權杖快取的個別伺服器上。部署使用第三方 OAuth 權杖的解決方案時，請仔細考慮導入 API 代理，協助管理代理程式可能傳送給第三方 OAuth 供應商的請求量。

服務代理 ID 權杖

Dialogflow CX 可以使用 Dialogflow CX 服務專員產生 ID 權杖。

Dialogflow CX 呼叫 Webhook 時，系統會在授權 HTTP 標頭中新增權杖。

授予「叫用者」角色權限後，您可以使用 ID 權杖存取 Cloud Run 資源。

[e-mail]

如果 Cloud Run 資源位於同一個資源專案中，您不需要額外的 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 用戶端程式庫或開放原始碼程式庫 (例如 github.com/googleapis/google-auth-library-nodejs) 驗證權杖。

服務帳戶

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

如果尚未建立服務帳戶，請建立服務帳戶。

由於服務帳戶是主體，因此可以授予角色來存取專案中的資源，就像您對任何其他主體所做的一樣。服務帳戶電子郵件地址會用於產生存取權杖，並在 Webhook 要求的 Authorization 標頭中傳送。

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

• roles/iam.serviceAccountUser

Dialogflow CX 必須具備下列權限，才能產生權杖：Dialogflow 服務代理程式

• roles/iam.serviceAccountTokenCreator

服務帳戶也必須具備存取代管 Webhook 服務的權限。

注意： 如要跨多個專案使用服務帳戶，請確認機構政策支援這項操作。這兩項權限都必須在包含服務帳戶的專案中授予。

Secret Manager 驗證

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

1. 如果沒有密鑰，請建立密鑰。
2. 為 Dialogflow 服務代理程式授予新密鑰的「Secret Manager 密鑰存取者」(roles/secretmanager.secretAccessor) 角色。
3. 將憑證複製到剪貼簿。
4. 為密鑰新增版本。將憑證貼到 Secret 值。
   • 如果您使用驗證標頭，請輸入 Bearer <YOUR_CREDENTIAL>。
   • 如果您使用基本使用者名稱和密碼驗證，請改為輸入 <YOUR_USERNAME>:<YOUR_PASSWORD>。
   • 結尾請省略任何換行字元。
5. 複製您剛新增的密鑰版本名稱。名稱格式為 projects/{project_id}/secrets/{secret_id}/versions/{version_id}"。
6. 開啟網路鉤子編輯畫面，然後：
   • 如果您使用驗證標頭，請建立新的密鑰版本要求標頭。輸入「Authorization」做為金鑰，然後將密鑰版本名稱貼到「密鑰版本」輸入方塊。
   • 如果您使用基本使用者名稱和密碼驗證，請按一下「基本驗證」下方的「密鑰版本」，然後將密鑰版本名稱貼到「密鑰版本」輸入框。
   • 如果您使用第三方 OAuth，請按一下「第三方 OAuth」下方的「密鑰版本」，然後將密鑰版本名稱貼到「密鑰版本」輸入框。
7. 按一下 [儲存]。

注意： 我們僅支援全域 Secret Manager。不支援使用區域性密鑰。

HTTPS 憑證驗證

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

特定環境的 Webhook

如果您使用環境將正式版系統與開發系統隔離 (建議採用這種做法)，可以將網路鉤子設為環境專屬。針對您定義的每個 Webhook 資源，您可以為代理程式定義的每個環境提供專屬網址和驗證設定。

您可以在安全無虞的環境中開發及測試 Webhook 程式碼更新，再部署至正式環境。

建立或編輯 Webhook 資源

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

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

控制台

1. 開啟 Dialogflow CX 控制台。
2. 選擇 Google Cloud 專案。
3. 選取代理程式。
4. 選取「管理」分頁標籤。
5. 按一下「Webhooks」。
6. 按一下「建立」，或按一下清單中的 Webhook 資源進行編輯。
7. 輸入標準 Webhook 資源設定 或彈性 Webhook 資源設定。
8. 按一下 [儲存]。

API

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

選取 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
Ruby	不適用	不適用

關閉

如要編輯 Webhook 的環境專屬設定，請參閱 Environment 類型的 patch 或 update 方法。 前往「Environment API」參考資料

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

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

關閉

Webhook 錯誤

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

• 400 不正確的要求
• 401 未經授權
• 403 禁止
• 404 找不到
• 500 伺服器錯誤
• 503 服務無法使用

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

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

此外，如果網頁服務呼叫是由 detect intent API 呼叫觸發，detect intent 回應中的 queryResult.webhookStatuses 欄位會包含網頁服務狀態資訊。

自動重試

Dialogflow CX 內建機制，可在發生特定 Webhook 錯誤時自動重試，以提升穩定性。系統只會重試非終端錯誤 (例如逾時或連線錯誤)。

如要降低重複呼叫的可能性，請採取下列做法：

• 設定較長的 Webhook 逾時門檻。
• 在 Webhook 邏輯中支援等冪性或重複資料刪除。

使用 Cloud Run

注意： 本節說明如何使用安全的 Cloud Run 資源，做為 Dialogflow CX 網路服務掛鉤。建議您確保資源安全。 不過，如果您選擇使用網址型使用者名稱和密碼或 HTTP 標頭進行驗證，則應允許未經驗證的存取權，以便存取 Cloud Run 資源。

Dialogflow CX 與 Cloud Run 整合，因此您可以建立安全的無伺服器 Webhook。如果您建立的 Cloud Run 資源與代理程式位於同一個專案，請在驗證設定中選取「Service Agent Auth -> ID Token」，確保代理程式能安全地呼叫 Webhook。

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

1. 您的虛擬服務專員專案必須有 Dialogflow CX 服務代理 服務帳戶，地址如下：

   [e-mail]

   建立專案的第一個代理程式時，系統通常會自動建立這個特殊服務帳戶和相關聯的金鑰。 如果您的代理程式是在 2020 年 11 月 1 日前建立，您可以觸發建立這個特殊服務帳戶：
   1. 為專案建立新代理程式。
   2. 執行下列指令：

      gcloud beta services identity create --service=dialogflow.googleapis.com --project=agent-project-id

2. 如果 Webhook 函式與代理程式位於不同專案，您必須在 Cloud Run 資源的專案中，將 Cloud Run Invoker 或 Cloud Functions Invoker IAM 角色提供給 Dialogflow CX 服務代理程式服務帳戶。
3. 在「Auth configuration」部分選取「Service Agent Auth -> ID Token」。

使用容器化 Webhook 和 Go ezcx 架構

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

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

注意： 不支援在 Dialogflow CX 代理程式專案的 VPC Service Controls perimeter 外部使用 Cloud Run 執行 Webhook。

只要代理程式位於相同專案或 VPC Service Controls 範圍內，設定為接受來自相同專案或 VPC Service Controls 範圍內 VPC 網路內部流量的 Cloud Run 資源，即可做為 Webhook 使用。

使用 Service Directory 存取私人網路

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

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

1. 請按照服務目錄私人網路設定，設定虛擬私有雲網路和服務目錄端點。

   注意： Dialogflow CX 會將 Service Directory 資訊快取 90 秒。也就是說，如果您更新服務目錄端點，變更會在 90 秒內生效。此外，如果您設定多個端點來提供備援，Dialogflow CX 可能會透過故障的端點傳送流量 90 秒。

2. 虛擬服務專員專案必須有下列地址的 Dialogflow CX 服務代理 服務帳戶：

   [e-mail]

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

   • servicedirectory.viewer
   • servicedirectory.pscAuthorizedService

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

3. 建立 Webhook 時，請提供 Service Directory 服務，以及網址和選填的驗證資訊。

   控制台

   

   API

   如需 Webhook 類型，請參閱 serviceDirectory 欄位。前往 Webhook API 參考資料

   為 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
   Ruby	不適用	不適用

   關閉

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

範例和疑難排解

請參閱Webhook 使用指南。