Webhooks

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

A webhook can either be a standard webhook or a flexible webhook. With a standard webhook, the request and response fields are defined by Dialogflow CX. With a flexible webhook, you define the request and response fields.

You can also access the HTTP status code of the webhook call using the $request.webhook_status_code request parameter.

Standard webhooks

With standard webhooks, you use Dialogflow CX-defined request and response messages. The request message provides many details about the session. For example, the current active page, recent matched intent, session parameter values, and agent-defined responses are all included.

Standard webhook request

When a fulfillment with a webhook is called, Dialogflow CX sends an HTTPS POST webhook request to your webhook service. The body of this request is a WebhookRequest JSON object with information about the session.

Some integrations populate the WebhookRequest.payload field with additional information. For example, the Dialogflow CX Phone Gateway integration provides the end-user caller ID.

For details, see the WebhookRequest (V3) or WebhookRequest (V3Beta1) reference documentation.

Standard webhook response

After your webhook service receives a request, it must send a response that meets these requirements:

• The response must occur within the timeout configured when creating the webhook resource.
• The response must be 64 KiB or smaller.

For details, see the WebhookResponse (V3) or WebhookResponse (V3Beta1) reference documentation.

Standard webhook resource settings

The following table describes webhook resource settings for standard webhooks:

X	Item
Display name	The name shown in the console for the webhook.
Webhook timeout	When Dialogflow CX 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 CX 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.
Subtype	Set to Standard.
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.

Flexible webhooks

With flexible webhooks, you define the request HTTP method, request URL parameters, and fields of the request and response messages. The request can only provide selected parameter values, and the response can only provide parameter override values. This simplifies the interface between the agent and the webhook, as there is rarely a need to communicate anything other than session parameter values. It also simplifies your webhook implementation because the request and response messages only contain what you need, and you can provide unique webhook messages for various scenarios.

Flexible webhook request

When you create the webhook resource for your agent, you can specify the following for webhook requests:

• The HTTP method used for webhook requests sent to your webhook service.
• Session parameter values that Dialogflow CX should send to your webhook service using the URL.
• Session parameter values that Dialogflow CX should send to your webhook service through the request JSON body if you choose POST, PUT, or PATCH as the method.

To send session parameter values using the request URL or JSON body, use parameter references. You don't need to URL-escape the parameter reference or wrap it in quotations. At runtime, Dialogflow CX URL-escapes the parameter value as needed. A list or composite value is provided as JSON.

When using a parameter reference in the JSON body, you must wrap the reference in quotations, regardless of the parameter's type. If the parameter is actually a numeric scalar, list, or composite value, Dialogflow CX will remove the quotes when sending the request at runtime to preserve the parameter data type. String scalar types will remain quoted. If a numeric scalar, list, or composite value is referenced within a string value (for example: "This is a number: $session.params.size"), the parameter will be treated as a string ("This is a number: 3").

For example, you can provide the fruit and size session parameter values to the request URL as follows:

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

And, to the request JSON body as follows:

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

Flexible webhook response

When creating the webhook resource for your agent, you can specify session parameters that Dialogflow CX should set to specific fields of the webhook response at runtime.

Your response must meet the following limitations:

• The response must occur within the timeout configured when creating the webhook resource, otherwise the request will time out.
• The response must be at most 64 KiB in size.

To specify a scalar, list, or composite field, use the following format:

$.fully.qualified.path.to.field

For example, consider the following JSON response:

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

To specify the "value" field, use the following:

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

Flexible webhook resource settings

The following table describes webhook resource settings for flexible webhooks.

X	Item
Display name	The name shown in the console for the webhook.
Webhook timeout	When Dialogflow CX 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 CX 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, which may include references to session parameters.
Subtype	Set to Flexible.
Method	Set the HTTP method for the webhook request.
Request body	Provide the request JSON body as described above.
Response configuration	Provide the session parameters that should be set to response fields as described above.
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.

Use a predefined custom template

Dialogflow offers predefined custom templates that you can use to integrate flexible webhooks with Salesforce CRM.

1. Go to the Manage tab, select Webhooks, and then click Create.
2. Under Subtype, select Flexible.
3. Click Configure using predefined template.
4. In the Integration type menu, select Salesforce.
5. In the API name menu, select an API name. The template automatically fills out the webhook form based on the API name you choose.
   1. Manually configure the following fields if applicable, based on your parameters:
      • Webhook URL
      • Method
      • Request body JSON
      • Response Configuration
   2. The required OAuth fields will be highlighted in the Authentication section.
6. Click Save.

Webhook service requirements

Your webhook service must meet the following requirements:

• Handle HTTPS requests. HTTP is unsupported. If you host your webhook service on Google Cloud using a Compute or Serverless computing solution, see the documentation for serving with HTTPS. For other hosting options, see Get an SSL certificate for your domain.
• Ensure the webhook service URL is publicly accessible, unless it is hosted as a Cloud Run resource or accessed as a Service directory webhook.
• Handle requests and responses as described in the standard webhook or flexible webhook section.
• If your agent does not integrate with Service Directory private network access, webhook calls are outside the service perimeter and are blocked when enabling VPC Service Controls. Service Directory supports limited endpoints; for details, refer to Service Directory.

Authentication

Secure your webhook service so that only you or your Dialogflow CX agent can make requests. Configure this when creating or editing a webhook resource. Dialogflow CX supports the following authentication mechanisms:

X	Item
Authentication headers	For webhook settings, you can specify optional HTTP header key-value pairs. If supplied, Dialogflow CX 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. If you use a static credential for the authorization header, we recommend you to supply your credential using Secret Manager.
Basic auth with username and password	For webhook settings, you can specify optional login username and password values. If supplied, Dialogflow CX adds an authorization HTTP header to webhook requests. This header is of the form: "authorization: Basic <base 64 encoding of the string username:password>". We recommend you to supply your username and password using Secret Manager.
Third-party OAuth	You can specify the Third-party OAuth configuration so that Dialogflow CX exchanges an access token from the OAuth system and adds it in the authorization HTTP header. Only client credential flow is supported. We recommend you to supply your client secret using Secret Manager.
Service agent access tokens	Discontinued.
Service account	You can use a service account for authentication. This can be used to access other Google Cloud APIs.
Service agent ID tokens	You can choose ID token in the Service agent authentication section, which lets you use Service agent ID token for authentication. This lets you access Cloud Run resources.
Mutual TLS authentication	See the Mutual TLS authentication documentation.

Note: If multiple authentication options are enabled, higher priority options take precedence. The priority order is as follows: Authentication headers, Basic auth, Third-party OAuth, Service agent auth.

Note: We don't recommend using IP ranges to authenticate webhook requests. If you choose to use the request's source IP to enable connectivity into your network perimeter, allow requests from the ranges listed at https://www.gstatic.com/ipranges/goog.json and deny connections from the ranges listed at https://www.gstatic.com/ipranges/cloud.json (these are Google's addresses that can be used to deploy third-party workloads). Dialogflow cannot guarantee IP ranges for machines that send webhook requests.

Note: After Aug 15, 2025, exported agents no longer contain raw value credentials for authentication headers, basic auth with username and password, or third-party OAuth.

Third-party OAuth

Dialogflow CX collects an access token from a third-party OAuth provider and adds it to the authorization HTTP header when making webhook requests.

The following table describes resource settings for third-party OAuth:

X	Item
Client ID	The Client ID to use when requesting an OAuth token.
Client Secret	The secret to use when requesting an OAuth token. We recommend you to supply your client secret using Secret Manager.
OAuth Endpoint URL	The URL to use to request an OAuth token.
OAuth Scopes	A comma-separated list of scopes that the OAuth token can be used for.

Requests sent to the OAuth endpoint URL to receive a token don't include the custom request headers configured for the webhook request. You can pass custom information to the OAuth server as parameters within the OAuth endpoint URL's query string.

Note: Third-party OAuth tokens are reused for webhook requests using the same client ID, endpoint URL, and scopes within the same Dialogflow CX agent so long as the request is made on the same Dialogflow CX server and the token has not expired. To achieve high availability, agents are deployed across many individual servers that don't share OAuth token caches. When deploying a solution that uses third-party OAuth tokens, carefully consider implementing an API proxy to help manage the volume of requests that your agent may send to your third-party OAuth provider.

Service agent ID token

Dialogflow CX can generate an ID token using the Dialogflow CX service agent. This token is added to the Authorization HTTP header when Dialogflow CX calls a webhook.

An ID token can be used to access Cloud Run resources after you grant the Cloud Run Invoker role (roles/run.invoker) to

[e-mail]

If the Cloud Run resources are in the same resource project, you don't need additional Identity and Access Management (IAM) permission to call them.

The audience used to generate the ID token is the entire webhook URL, excluding any query parameters. If you are using Cloud Run, ensure that this URL is supported by the Cloud Run audiences.

For example, if the webhook URL is:

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

the following URL needs to be in custom audiences:

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

Any webhook can also optionally validate the token using Google client libraries or open-source libraries like the Google Auth Library for Node.js.

If your webhook is hosted on Cloud Run and accessed through a load balancer, add your load balancer's URL as a custom audience to your Cloud Run. For more information about custom audiences, see Set custom audiences for services.

Service Account

Service accounts can be used to authenticate webhook requests to any Google APIs that support them.

If you haven't already, create a service account.

Because service accounts are principals, they can access resources in your project by granting them a role, just like any other principal. The service account email is used to generate an access token that is sent in the Authorization header of the webhook request.

To configure the webhook to use service accounts, you must have the following permissions:

• roles/iam.serviceAccountUser

To generate tokens, the Dialogflow Service Agent must have the following permissions:

• roles/iam.serviceAccountTokenCreator

The service account must also have permissions to access the service that hosts the webhook.

Note: If you are trying to use service accounts across multiple projects, ensure that your organization policy supports it. Both permissions must be granted in the project that contains the service account.

Secret Manager Authentication

If you use authentication headers, basic auth with username and password, or third-party OAuth, you can store the credentials as secrets using Secret Manager. The following are the necessary steps to authenticate your webhook using secrets:

1. Create your secret if you don't have one.
2. Grant the Dialogflow Service Agent the Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) role on the new secret.
3. Copy your credential to the clipboard.
4. Add a new secret version to your secret and paste your credential as the secret value:
   • If you use authentication headers, enter Bearer <YOUR_CREDENTIAL>.
   • If you use basic username and password authentication, enter <YOUR_USERNAME>:<YOUR_PASSWORD>.
   • Omit any newline character at the end.
5. Copy the name of the secret version you added. The name format is projects/<var>PROJECT_ID</var>/secrets/<var>SECRET_ID</var>/versions/<var>VERSION_ID</var>.
6. Open the webhook edit screen.
7. Configure the authentication settings:
   • If you use authentication headers, create a new Secret version request header. Enter "Authorization" in the Key field, and paste the secret version name into the Secret version field.
   • For basic username and password authentication, click Secret version under Basic Auth, and paste the secret version name into the Secret version field.
   • If you use Third-party OAuth, click Secret version under Third-party OAuth, and paste the secret version name into the Secret version field.
8. Click Save.

Note: We only support global Secret Manager secrets. We don't support regional secrets.

HTTPS certificate verification

Dialogflow CX 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, see Custom CA certificates.

Environment-specific webhooks

If you use environments to isolate production from development, you can configure your webhooks to be environment-specific. You can provide environment-specific URL and authentication settings for each webhook resource.

This configuration lets you safely develop and test your webhook code updates before deploying them to production.

Create or edit webhook resources

After you have a webhook service running, create a webhook resource in your agent that includes connectivity and authentication information. You can edit webhook resource settings at any time.

To create or edit a webhook resource:

Console

1. Open the Dialogflow CX console.
2. Go to your project.
3. Select your agent.
4. Click the Manage tab.
5. Click Webhooks.
6. Click Create or select an existing webhook to edit.
7. Configure the standard webhook resource settings or flexible webhook resource settings.
8. Click Save.

API

For information about creating a webhook resource, see the create method for the Webhook type. For information about editing a webhook resource (except for environment-specific settings), see the patch or update 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++	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

Close

For information about editing the environment-specific settings for a webhook, see the patch or update method for the Environment type. Go to the Environment API reference

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

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

Dialogflow CX invokes a webhook error or timeout built-in event and continues processing as usual in the following error situations:

• The response timeout is exceeded.
• An error status code is received.
• The response is invalid.
• The webhook service is unavailable.

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.

Automatic retries

Dialogflow CX includes internal mechanisms that automatically retry on certain webhook errors to improve robustness. It only retries non-terminal errors, such as timeout or connection errors.

To reduce the likelihood of duplicated calls:

• Use longer webhook timeout thresholds.
• Implement idempotency in webhook logic or deduplicate requests.

Using Cloud Run

Caution: This section describes how to use secure Cloud Run resources for Dialogflow CX webhooks. Keeping your resources secure is recommended. If you choose to authenticate with URL-based username and password, or HTTP headers, you must allow unauthenticated access to your Cloud Run resource.

Dialogflow CX integrates with Cloud Run, so you can create a secure, serverless webhook. If you create a Cloud Run resource that resides in the same project as your agent, select Service Agent Auth, and then select ID token in authentication configuration so that your agent can securely call your webhook.

You must manually set up this integration in the following two situations:

1. The Dialogflow CX 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 can 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 Run Invoker or Cloud Functions Invoker IAM role to the Dialogflow CX Service Agent service account in your Cloud Run resource project.

Next, select Service Agent Auth > ID Token in the Auth configuration section.

Using containerized webhooks and the Go ezcx framework

To implement a containerized webhook using Go, see the Go ezcx framework. This framework simplifies many of the steps required to create a webhook.

Using Cloud Run with internal only traffic

Note: The use of Cloud Run outside the VPC Service Controls perimeter of the Dialogflow CX agent project for webhooks is not supported.

You can use Cloud Run resources configured to accept internal traffic from Virtual Private Cloud (VPC) networks in the same project or the same VPC Service Controls perimeter as a webhook, provided the agent is in the same project or the same VPC Service Controls perimeter.

Using Service Directory for private network access

Dialogflow CX 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:

1. Follow Service Directory private network configuration to configure your VPC network and Service Directory endpoint.

   Note: Dialogflow CX caches Service Directory information for 90 seconds. This means that when you update the Service Directory endpoint, the change takes 90 seconds to occur.

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

   [e-mail]

   Grant the following roles to the Dialogflow CX Service Agent service account in the project where your Service Directory is located:

   • servicedirectory.viewer
   • servicedirectory.pscAuthorizedService

   Additionally, if your Service Directory is in a different project than your Dialogflow CX agent, you also need to grant the servicedirectory.viewer role to the Dialogflow CX Service Agent account in the project that hosts your Dialogflow CX agent.

3. Specify the Service Directory service, the URL, and any optional authentication information when you create the webhook.

   Console

   

   API

   See the serviceDirectory field 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++	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

   Close

To troubleshoot issues, you can set up a private uptime check to verify that your Service Directory is configured correctly.

Samples and troubleshooting

For more information, see the webhook how-to guide.