CX webhooks are similar to ES webhooks, except that request and response fields have been changed to support CX features.
Webhook service requirements
The following requirements must be met by your webhook service:
- It must handle HTTPS requests. HTTP is not supported. If you host your webhook service on Google Cloud Platform using a Compute or Serverless Computing solution, see the product documentation for serving with HTTPS. For other hosting options, see Get an SSL certificate for your domain.
- Its URL for requests must be publicly accessible.
- It must handle POST requests with a JSON
- It must respond to
WebhookRequestrequests with a JSON
It's important to secure your webhook service, so that only you or your Dialogflow agent are authorized to make requests. This is configured when creating a webhook resource. Dialogflow CX supports the following mechanisms for authentication:
- Authentication with authentication headers
- Using Cloud Functions
- Service identity tokens
- Mutual TLS authentication
When a fulfillment with a webhook is called, Dialogflow sends an HTTPS POST webhook request to your webhook service. The body of this request is a JSON object with information about the matched intent.
reference documentation for details.
Once your webhook service receives a webhook request, it needs to send a webhook response. The following limitations apply to your response:
- The response must occur within a timeout that you configure when creating the webhook resource, otherwise the request will time out.
- The response must be less than or equal to 64 KiB in size.
reference documentation for details.
Create a webhook resource
Once you have a webhook service running, you need to create a webhook resource in your agent that has connectivity and authentication information. To create a webhook resource:
- Open the Dialogflow CX Console.
- Choose your GCP project.
- Select your agent.
- Select the Manage tab.
- Click Webhooks.
- Click Create.
- Enter webhook data.
- Click Save.
create method for the
Select a protocol and version for the Webhook reference:
|REST||Webhook resource||Webhook resource|
|RPC||Webhook interface||Webhook interface|
|C#||Not available||Not available|
|Go||Not available||Not available|
|PHP||Not available||Not available|
|Ruby||Not available||Not available|
If your webhook service encounters an error while handling a webhook request, your webhook code should return one of the following HTTP status codes:
In any of the following error situations, Dialogflow invokes a webhook error or timeout built-in event and continues processing as usual:
- Response timeout exceeded.
- Error status code received.
- Response is invalid.
- Webhook service is unavailable.
In addition, if the webhook service call
was triggered by a detect intent API call,
queryResult.webhookStatuses field in the detect intent response
contains the webhook status information.
Using Cloud Functions
Dialogflow integrates with Cloud Functions, so you can easily create a secure, serverless webhook. If you create a function that resides in the same project as your agent, your agent can securely call your webhook without needing any special configuration.
However, there are two situations in which you must manually setup this integration:
- The Dialogflow Service Agent
with the following address must exist for your agent project:
email@example.comThis special service account and the associated key is normally created automatically when you create the first agent for a project. If your agent was created before November 01, 2020, you may trigger creation of this special service account:
- Create a new agent for the project.
- Execute the following command:
gcloud beta services identity create --service=dialogflow.googleapis.com --project=agent-project-id
- If your webhook function resides in a different project than the agent, you must provide the Cloud Functions Invoker IAM role to the Dialogflow Service Agent service account in your function's project.
Service identity tokens
When Dialogflow calls a webhook, it provides a Google identity token with the request. Any webhook can optionally validate the token using Google client libraries or open source libraries like github.com/googleapis/google-auth-library-nodejs.