Webhooks

Webhooks are services that host your business logic. During a session, webhooks allow you to use the data extracted by Dialogflow's natural language processing to generate dynamic responses, validate collected data, or trigger actions on the backend.

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 WebhookRequest body.
• It must respond to WebhookRequest requests with a JSON WebhookResponse body.

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:

• Authentication with authentication headers
• Using Cloud Functions
• Service identity tokens
• Mutual TLS authentication

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 JSON object with information about the matched intent.

Note: REST JSON documentation for this type should be the primary reference, because this type is only sent via the REST JSON protocol. Due to an internal documentation generation bug, the documentation for this type cannot be produced for REST. Please see the field descriptions in the RPC documentation and translate to JSON until this bug is resolved.

See the WebhookRequest 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.

Note: REST JSON documentation for this type should be the primary reference, because this type is only sent via the REST JSON protocol. Due to an internal documentation generation bug, the documentation for this type cannot be produced for REST. Please see the field descriptions in the RPC documentation and translate to JSON until this bug is resolved.

See the WebhookResponse 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:

Console

1. Open the Dialogflow CX Console.
2. Choose your GCP project.
3. Select your agent.
4. Select the Manage tab.
5. Click Webhooks.
6. Click Create.
7. Enter webhook data.
8. Click Save.

API

See the create method for the Webhook type. Go to the Webhook API reference

Select a protocol and version for the Webhook reference:

Protocol	V3	V3beta1
REST	Webhook resource	Webhook resource
RPC	Webhook interface	Webhook interface
C#	Not available	Not available
Go	Not available	Not available
Java	WebhooksClient	WebhooksClient
Node.js	WebhooksClient	WebhooksClient
PHP	Not available	Not available
Python	WebhooksClient	WebhooksClient
Ruby	Not available	Not available

Close

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 Request
• 401 Unauthorized
• 403 Forbidden
• 404 Not found
• 500 Server fault
• 503 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:

1. The Dialogflow Service Agent service account with the following address must exist for your agent project:

   [e-mail]

   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:
   1. Create a new agent for the project.
   2. Execute the following command:

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

2. 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.