REST Resource: projects.locations.agents.webhooks

Resource: Webhook

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

JSON representation 
{
  "name": string,
  "displayName": string,
  "timeout": string,
  "disabled": boolean,

  // Union field webhook can be only one of the following:
  "genericWebService": {
    object (GenericWebService)
  },
  "serviceDirectory": {
    object (ServiceDirectoryConfig)
  }
  // End of list of possible types for union field webhook.
}
Fields
name

string

The unique identifier of the webhook. Required for the Webhooks.UpdateWebhook method. Webhooks.CreateWebhook populates the name automatically. Format: projects/<ProjectID>/locations/<LocationID>/agents/<AgentID>/webhooks/<WebhookID>.
displayName

string

Required. The human-readable name of the webhook, unique within the agent.
timeout

string (Duration format)

Webhook execution timeout. Execution is considered failed if Dialogflow doesn't receive a response from webhook at the end of the timeout period. Defaults to 5 seconds, maximum allowed timeout is 30 seconds.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".
disabled

boolean

Indicates whether the webhook is disabled.
Union field webhook. Required. The webhook configuration. webhook can be only one of the following:
genericWebService

object (GenericWebService)

Configuration for a generic web service.
serviceDirectory

object (ServiceDirectoryConfig)

Configuration for a Service Directory service.

GenericWebService

Represents configuration for a generic web service.

JSON representation 
{
  "uri": string,
  "username": string,
  "password": string,
  "requestHeaders": {
    string: string,
    ...
  },
  "allowedCaCerts": [
    string
  ],
  "oauthConfig": {
    object (OAuthConfig)
  },
  "serviceAgentAuth": enum (ServiceAgentAuth),
  "webhookType": enum (WebhookType),
  "httpMethod": enum (HttpMethod),
  "requestBody": string,
  "parameterMapping": {
    string: string,
    ...
  }
}
Fields
uri

string

Required. The webhook URI for receiving POST requests. It must use https protocol.
username
(deprecated)

string

The user name for HTTP Basic authentication.
password
(deprecated)

string

The password for HTTP Basic authentication.
requestHeaders

map (key: string, value: string)

The HTTP request headers to send together with webhook requests.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
allowedCaCerts[]

string (bytes format)

Optional. Specifies a list of allowed custom CA certificates (in DER format) for HTTPS verification. This overrides the default SSL trust store. If this is empty or unspecified, Dialogflow will use Google's default trust store to verify certificates. N.B. Make sure the HTTPS server certificates are signed with "subject alt name". For instance a certificate can be self-signed using the following command,

   openssl x509 -req -days 200 -in example.com.csr \
     -signkey example.com.key \
     -out example.com.crt \
     -extfile <(printf "\nsubjectAltName='DNS:www.example.com'")

A base64-encoded string.
oauthConfig

object (OAuthConfig)

Optional. The OAuth configuration of the webhook. If specified, Dialogflow will initiate the OAuth client credential flow to exchange an access token from the 3rd party platform and put it in the auth header.
serviceAgentAuth

enum (ServiceAgentAuth)

Optional. Indicate the auth token type generated from the Diglogflow service agent. The generated token is sent in the Authorization header.
webhookType

enum (WebhookType)

Optional. Type of the webhook.
httpMethod

enum (HttpMethod)

Optional. HTTP method for the flexible webhook calls. Standard webhook always uses POST.
requestBody

string

Optional. Defines a custom JSON object as request body to send to flexible webhook.
parameterMapping

map (key: string, value: string)

Optional. Maps the values extracted from specific fields of the flexible webhook response into session parameters. - Key: session parameter name - Value: field path in the webhook response

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

OAuthConfig

Represents configuration of OAuth client credential flow for 3rd party API authentication.

JSON representation 
{
  "clientId": string,
  "clientSecret": string,
  "tokenEndpoint": string,
  "scopes": [
    string
  ]
}
Fields
clientId

string

Required. The client ID provided by the 3rd party platform.
clientSecret

string

Required. The client secret provided by the 3rd party platform.
tokenEndpoint

string

Required. The token endpoint provided by the 3rd party platform to exchange an access token.
scopes[]

string

Optional. The OAuth scopes to grant.

ServiceAgentAuth

Indicate the auth token type generated from the Diglogflow service agent.

Enums
SERVICE_AGENT_AUTH_UNSPECIFIED Service agent auth type unspecified. Default to ID_TOKEN.
NONE No token used.
ID_TOKEN Use ID token generated from service agent. This can be used to access Cloud Function and Cloud Run after you grant Invoker role to service-<PROJECT-NUMBER>@gcp-sa-dialogflow.iam.gserviceaccount.com.
ACCESS_TOKEN Use access token generated from service agent. This can be used to access other Google Cloud APIs after you grant required roles to service-<PROJECT-NUMBER>@gcp-sa-dialogflow.iam.gserviceaccount.com.

WebhookType

Represents the type of webhook configuration.

Enums
WEBHOOK_TYPE_UNSPECIFIED Default value. This value is unused.
STANDARD Represents a standard webhook.
FLEXIBLE Represents a flexible webhook.

HttpMethod

HTTP method to use when calling webhooks.

Enums
HTTP_METHOD_UNSPECIFIED HTTP method not specified.
POST HTTP POST Method.
GET HTTP GET Method.
HEAD HTTP HEAD Method.
PUT HTTP PUT Method.
DELETE HTTP DELETE Method.
PATCH HTTP PATCH Method.
OPTIONS HTTP OPTIONS Method.

ServiceDirectoryConfig

Represents configuration for a Service Directory service.

JSON representation 
{
  "service": string,
  "genericWebService": {
    object (GenericWebService)
  }
}
Fields
service

string

Required. The name of Service Directory service. Format: projects/<ProjectID>/locations/<LocationID>/namespaces/<NamespaceID>/services/<ServiceID>. Location ID of the service directory must be the same as the location of the agent.
genericWebService

object (GenericWebService)

Generic Service configuration of this webhook.

Methods

create

 Creates a webhook in the specified agent.

delete

 Deletes the specified webhook.

get

 Retrieves the specified webhook.

list

 Returns the list of all webhooks in the specified agent.

patch

 Updates the specified webhook.