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 Conversational Agents (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 Conversational Agents (Dialogflow CX). With a flexible webhook, you define the request and response fields.

Standard webhooks

With standard webhooks, you use Conversational Agents (Dialogflow CX)-defined request and response messages. The request message provides many details about the session. For example, 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, Conversational Agents (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.

See the WebhookRequest(V3) or WebhookRequest(V3Beta1) reference documentation for details.

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

Standard webhook resource settings

The following describes webhook resource settings for standard webhooks:

Term Definition
Display name The name shown in the console for the webhook.
Webhook timeout When Conversational Agents (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, Conversational Agents (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 limitation is actually beneficial, because it simplifies the interface between the agent and the webhook. There is rarely a need to communicate anything other than session parameter values between an agent and a webhook. 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 creating 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 Conversational Agents (Dialogflow CX) should send to your webhook service using the URL.
  • If you choose POST, PUT, or PATCH as the method, you can specify session parameter values that Conversational Agents (Dialogflow CX) should send to your webhook service through the request JSON body.

To send session parameter values using the request URL or JSON body, use parameter references as you normally would. You do not need to URL-escape the parameter reference, and you do not wrap the reference in quotations. At runtime, Conversational Agents (Dialogflow CX) will URL-escape the parameter value as needed. A list or composite value will be 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, Conversational Agents (Dialogflow CX) will remove the quotes when sending the request at runtime to preserve the parameter's datatype. String scalar types will remained 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 like this:

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

And, to the request JSON body like this:

{
  "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 Conversational Agents (Dialogflow CX) should set to specific fields of the webhook response at runtime.

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.

Use the following format to specify a scalar, list, or composite field:

$.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 describes webhook resource settings for flexible webhooks:

Term Definition
Display name The name shown in the console for the webhook.
Webhook timeout When Conversational Agents (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, Conversational Agents (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. Under the Manage tab, click Webhooks and then + Create.

  2. Under Subtype, select Flexible.

  3. Click Configure using predefined template to enable the feature.

  4. In the Integration type drop-down menu, select Salesforce.

  5. In the API name drop-down menu, select an API name. The template automatically fills out the webhook form based on the API name you choose.

    1. You can 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 to create the webhook.

Webhook service requirements

The following requirements must be met by your webhook service:

Authentication

It's important to secure your webhook service, so that only you or your Conversational Agents (Dialogflow CX) agent are authorized to make requests. This is configured when creating a webhook resource. Conversational Agents (Dialogflow CX) supports the following mechanisms for authentication:

Term Definition
Authentication headers For webhook settings, you can specify optional HTTP header key-value pairs. If supplied, Conversational Agents (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.
Basic auth with username and password For webhook settings, you can specify optional login username and password values. If supplied, Conversational Agents (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>".
Third-party OAuth You can specify the Third-party OAuth configuration so that Conversational Agents (Dialogflow CX) exchanges an access token from the OAuth system and adds it in the authorization HTTP header. Only client credential flow is supported.
Service agent access tokens You can select access token in Service agent auth to use service agent access tokens for authentication. This can be used to access other Google Cloud APIs.
Service agent ID tokens You can select ID token in Service agent auth to use service agent ID tokens for authentication. This can be used to access Cloud Run functions and Cloud Run services.
Mutual TLS authentication See the Mutual TLS authentication documentation.

Third-party OAuth

Conversational Agents (Dialogflow CX) can collect an access token from a third-party OAuth provider and add it to the authorization HTTP header when making its webhook requests.

The following describes resource settings for third-party OAuth:

Term Definition
Client ID The Client ID to use when requesting an OAuth token.
Client Secret The secret to use when requesting an OAuth token.
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.

Service agent access tokens

Conversational Agents (Dialogflow CX) can generate an ID token or access token using Conversational Agents (Dialogflow CX) service agent.

The token is added in the authorization HTTP header when Conversational Agents (Dialogflow CX) calls a webhook.

ID token

An ID token can be used to access Cloud Run functions and Cloud Run services after you grant Invoker role to

service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
If the Cloud Run functions and Cloud Run services are in the same resource project, you don't need additional IAM permission to call them.

The audience used to generate the ID token will be the entire webhook URL except any query parameters. If you are using Cloud Run, make sure 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 github.com/googleapis/google-auth-library-nodejs.

Access token

An access token can be used to access other Google Cloud APIs after you grant required roles to

service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com

HTTPS certificate verification

Conversational Agents (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, please refer to 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

  1. Open the Dialogflow CX console.
  2. Choose your Google Cloud project.
  3. Select your agent.
  4. Select the Manage tab.
  5. Click Webhooks.
  6. Click Create or click a webhook resource in the list to edit.
  7. Enter standard webhook resource settings or flexible webhook resource settings.
  8. 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 Request
  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not found
  • 500 Server fault
  • 503 Service Unavailable

In any of the following error situations, Conversational Agents (Dialogflow CX) 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.

Automatic retries

Conversational Agents (Dialogflow CX) includes internal mechanisms that automatically retry on certain webhook errors to improve robustness. Only non-terminal errors are retried (for example, timeout or connection errors).

To reduce the likelihood of duplicated calls:

  • Set longer webhook timeout thresholds.
  • Support idempotency in webhook logic or deduplicate.

Using Cloud Run functions

Conversational Agents (Dialogflow CX) integrates with Cloud Run functions, so you can easily create a secure, serverless webhook. If you create a function that resides in the same project as your agent, you just need to select Service Agent Auth -> ID Token in the Auth configuration, your agent can then securely call your webhook.

However, there are two situations in which you must manually setup this integration:

  1. The Conversational Agents (Dialogflow CX) 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:
    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 Conversational Agents (Dialogflow CX) Service Agent service account in your function's project.
  3. Select Service Agent Auth -> ID Token in the Auth configuration section.

Using containerized webhooks and the Go ezcx framework

If you would like to implement a containerized webhook using Go, see the Go ezcx framework. This framework can simplify many of the steps required when creating a webhook.

Using Cloud Run functions with internal only traffic

Cloud Run functions set up to accept internal traffic from VPC networks in the same project or the same VPC SC perimeter can be used as a webhook as long as the agent is in the same project or same VPC SC perimeter.

Using Service Directory for private network access

Conversational Agents (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.

  2. The Conversational Agents (Dialogflow CX) 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 Conversational Agents (Dialogflow CX) Service Agent service account the following IAM roles:

    • servicedirectory.viewer of the Service Directory project
    • servicedirectory.pscAuthorizedService of the network project
  3. Provide Service Directory Service along with the URL and optional authentication information when creating the webhook.

    Console

    Service Directory Webhook screenshot.

    API

    See the serviceDirectory field 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 troubleshoot issues, you can set up a private uptime check to check that your Service Directory is correctly configured.

Samples and troubleshooting

See the webhook how-to guide.