Webhook service

To use fulfillment in a production system, you should implement and deploy a webhook service. The detailed processing flow for fulfillment and webhooks is described in the fulfillment overview document.

Your webhook service needs to handle HTTPS POST requests with a JSON body and return a JSON body. This document describes the details of enabling a webhook, handling a webhook request, and sending a webhook response.

Authentication

It's important to secure your webhook service, so that only you or your Dialogflow agent are authorized to make requests. Your webhook must use HTTPS, and the URL for webhook requests must be publicly accessible. Dialogflow supports the following mechanisms for authentication:

  • Basic authentication with login and password. This is configured when enabling fulfillment.
  • Authentication with authentication headers. This is configured when enabling fulfillment.
  • Mutual TLS authentication.

Webhook request

When an intent configured for fulfillment is matched, 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.

Here is a sample request:

{
  "responseId": "response-id",
  "session": "projects/project-id/agent/sessions/session-id",
  "queryResult": {
    "queryText": "End-user expression",
    "parameters": {
      "param-name": "param-value"
    },
    "allRequiredParamsPresent": true,
    "fulfillmentText": "Response configured for matched intent",
    "fulfillmentMessages": [
      {
        "text": {
          "text": [
            "Response configured for matched intent"
          ]
        }
      }
    ],
    "outputContexts": [
      {
        "name": "projects/project-id/agent/sessions/session-id/contexts/context-name",
        "lifespanCount": 5,
        "parameters": {
          "param-name": "param-value"
        }
      }
    ],
    "intent": {
      "name": "projects/project-id/agent/intents/intent-id",
      "displayName": "matched-intent-name"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {},
    "languageCode": "en"
  },
  "originalDetectIntentRequest": {}
}

Webhook response

Once your webhook receives a webhook request, it needs to send a webhook response. The body of this response is a JSON object with the following information:

The following limitations apply to your response:

  • The response must occur within 10 seconds for Google Assistant applications or 5 seconds for all other applications, 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.

Here is a sample response:

{
  "fulfillmentText": "This is a text response",
  "fulfillmentMessages": [
    {
      "card": {
        "title": "card title",
        "subtitle": "card text",
        "imageUri": "https://example.com/images/example.png",
        "buttons": [
          {
            "text": "button text",
            "postback": "https://example.com/path/for/end-user/to/follow"
          }
        ]
      }
    }
  ],
  "source": "example.com",
  "payload": {
    "google": {
      "expectUserResponse": true,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "this is a simple response"
            }
          }
        ]
      }
    },
    "facebook": {
      "text": "Hello, Facebook!"
    },
    "slack": {
      "text": "This is a text response for Slack."
    }
  },
  "outputContexts": [
    {
      "name": "projects/project-id/agent/sessions/session-id/contexts/context-name",
      "lifespanCount": 5,
      "parameters": {
        "param-name": "param-value"
      }
    }
  ],
  "followupEventInput": {
    "name": "event name",
    "languageCode": "en-US",
    "parameters": {
      "param-name": "param-value"
    }
  }
}

Enable fulfillment

To enable fulfillment for your agent:

  1. Go to the Dialogflow Console.
  2. Select an agent.
  3. Select Fulfillment in the left sidebar menu.
  4. Toggle the Webhook field to Enabled.
  5. Provide the details for your webhook service in the form. If your webhook doesn't require authentication, leave the authentication fields blank.
  6. Click Save at the bottom of the page.

Screenshot of enabling fulfillment.

To enable fulfillment for an intent:

  1. Select Intents in the left sidebar menu.
  2. Select an intent.
  3. Scroll down to the Fulfillment section.
  4. Toggle Enable webhook call for this intent to on.
  5. Click Save.

Webhook errors

If your webhook service encounters an error, it 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 responds to the end-user with the built-in response configured for the intent currently matched:

  • Response timeout exceeded.
  • Error status code received.
  • Response is invalid.
  • Webhook service is unavailable.

In addition, if the intent match was triggered by a detect intent API call, the status field in the detect intent response contains the webhook error information. For example:

"status": {
    "code": 206,
    "errorType": "webhook call failed with %error Code% error"
}