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:

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.

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.

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.

Select a protocol and version for the Webhook reference:

Protocol V3beta1
REST Webhook resource
RPC Webhook interface
Java WebhooksClient
Node.js WebhooksClient
Python WebhooksClient

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.