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, unless it is hosted as a Cloud Function.
- It must handle POST requests with a JSON
WebhookRequest
body and respond with a JSONWebhookResponse
body. - If your agent does not integrate with Service Directory private network access, webhook calls are considered outside the service perimeter and are blocked when enabling VPC Service Controls. Limited endpoints are supported by Service Directory; refer to Service Directory for details.
Authentication
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:
Term | Definition |
---|---|
Login username and password | For webhook settings, you can specify optional login username and password values. If supplied, Dialogflow adds an authorization HTTP header to webhook requests. This header is of the form: "authorization: Basic <base 64 encoding of the string username:password>" . |
Authentication headers | For webhook settings, you can specify optional HTTP header key-value pairs. If supplied, Dialogflow adds these HTTP headers to webhook requests. It is common to provide a single pair with a key of authorization . The header values support session parameter references and system function parsing like in static response messages. |
Cloud Functions built-in authentication | You can use the built-in authentication when using Cloud Functions. In order to use this type of authentication, do not supply login username, login password, or authorization headers. If you do supply any of these fields, these fields will be used for authentication rather than the built-in authentication. |
Service identity tokens | You can use service identity tokens for authentication. If you do not supply login username, login password, or a header with a key of authorization , Dialogflow automatically assumes that service identity tokens should be used and adds an authorization HTTP header to webhook requests. This header is of the form: "authorization: Bearer <identity token>" . |
Mutual TLS authentication | See the Mutual TLS authentication documentation. |
HTTPS certificate verification
Dialogflow by default uses Google's default trust store to verify HTTPS certificates. If you intend to use certificates not recognized by Google's default trust store for your HTTPS server, such as self-signed certificates or custom root certificates, please refer to Custom CA certificates.
Webhook request
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 WebhookRequest
JSON object
with information about the matched intent.
Some
integrations
populate the WebhookRequest.payload
field with additional information.
For example, the
Dialogflow CX phone gateway integration
provides the end-user caller ID.
See the
WebhookRequest
(V3)
or
WebhookRequest
(V3Beta1)
reference documentation for details.
Webhook response
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.
See the
WebhookResponse
(V3)
or
WebhookResponse
(V3Beta1)
reference documentation for details.
Webhook resource settings
The following describes webhook resource settings:
Term | Definition |
---|---|
Display name | The name shown in the console for the webhook. |
Webhook timeout | When Dialogflow sends a webhook request to your webhook service, it may timeout while waiting for a response. This setting controls that timeout in seconds. If a timeout occurs, Dialogflow invokes a webhook.error.timeout event. |
Type | Set to Service directory if you are using service directory for private network access, otherwise set to Generic web service. |
Webhook URL | Provide the URL address for your webhook service. |
Environment-specific webhook | You can provide environment-specific webhooks. |
Authentication | See the authentication section. |
Custom CA certificate | This is used to upload custom CA certificates. |
Environment-specific webhooks
If you are using environments to isolate production systems from development systems (recommended), you can configure your webhooks to be environment-specific. For each webhook resource you define, you can provide unique URL and authentication settings for each environment that you have defined for the agent.
This allows you to safely develop and test your webhook code updates before deploying them to production.
Create or edit webhook resources
Once you have a webhook service running, you need to create a webhook resource in your agent that has connectivity and authentication information. After creation, you can also edit webhook resource settings at any time.
To create or edit a webhook resource:
Console
- Open the Dialogflow CX Console.
- Choose your GCP project.
- Select your agent.
- Select the Manage tab.
- Click Webhooks.
- Click Create or click a webhook resource in the list to edit.
- Enter webhook resource settings.
- Click Save.
API
To create a webhook resource, see the create
method for the Webhook
type.
To edit a webhook resource (except for environment-specific settings),
see the patch
or update
method for the Webhook
type.
Select a protocol and version for the Webhook reference:
Protocol | V3 | V3beta1 |
---|---|---|
REST | Webhook resource | Webhook resource |
RPC | Webhook interface | Webhook interface |
C++ | WebhooksClient | Not available |
C# | WebhooksClient | Not available |
Go | WebhooksClient | Not available |
Java | WebhooksClient | WebhooksClient |
Node.js | WebhooksClient | WebhooksClient |
PHP | Not available | Not available |
Python | WebhooksClient | WebhooksClient |
Ruby | Not available | Not available |
To edit the environment-specific settings for a webhook,
see the patch
or update
method for the Environment
type.
Select a protocol and version for the Environment reference:
Protocol | V3 | V3beta1 |
---|---|---|
REST | Environment resource | Environment resource |
RPC | Environment interface | Environment interface |
C++ | EnvironmentsClient | Not available |
C# | EnvironmentsClient | Not available |
Go | EnvironmentsClient | Not available |
Java | EnvironmentsClient | EnvironmentsClient |
Node.js | EnvironmentsClient | EnvironmentsClient |
PHP | Not available | Not available |
Python | EnvironmentsClient | EnvironmentsClient |
Ruby | Not available | Not available |
Webhook errors
If your webhook service encounters an error while handling a webhook request, your webhook code should return one of the following HTTP status codes:
400
Bad Request401
Unauthorized403
Forbidden404
Not found500
Server fault503
Service Unavailable
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,
the 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
service account
with the following address must exist for your agent project:
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
This 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.
Using Service Directory for private network access
Dialogflow integrates with Service Directory private network access, so it can connect to webhook targets inside your VPC network. This keeps the traffic within the Google Cloud network and enforces IAM and VPC Service Controls.
To set up a webhook targeting a private network:
Follow Service Directory private network configuration to configure your VPC network and Service Directory endpoint.
The Dialogflow Service Agent service account with the following address must exist for your agent project:
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
Grant the Dialogflow Service Agent service account the following IAM roles:servicedirectory.viewer
of the Service Directory projectservicedirectory.pscAuthorizedService
of the network project
Provide Service Directory Service along with the URL and optional authentication information when creating the webhook.
Console
API
See the
serviceDirectory
field for theWebhook
type.Select a protocol and version for the Webhook reference:
Protocol V3 V3beta1 REST Webhook resource Webhook resource RPC Webhook interface Webhook interface C++ WebhooksClient Not available C# WebhooksClient Not available Go WebhooksClient Not available Java WebhooksClient WebhooksClient Node.js WebhooksClient WebhooksClient PHP Not available Not available Python WebhooksClient WebhooksClient Ruby Not available Not available
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.
For example, you can verify the email
of the ID token as:
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
Samples
The following samples show how to receive a WebhookRequest and send a WebhookResponse.