This page offers useful information about webhooks in Chat. You will find information about the following topics:

• Transactions Architecture
• Webhook handshake
• Webhook Request Format
• Webhook Response Format
• Using a webhook to capture Multiple-value variables
• Using webhooks to reset variables
• Webhook timeout limit and proxies
• Webhook restrictions
• Special considerations using AWS

Transactions Architecture

The Inbenta Chat app can connect to external services to carry out data retrieval operations from your data services and to request the execution of operations into your transactional systems.

The architecture diagram below outlines how Inbenta can establish this communication through the configuration of webhooks (This link opens a third-party website that is not affiliated with Inbenta).

As the diagram shows, there are two different paths to execute a transaction:

• Consume a webhook hosted in your infrastructure (your webhook then connects directly with the transactional system within your network):
  • The diagram also describes how Inbenta can securely establish this external connection by going through a NAT Gateway. This makes sure that all outgoing Chat connections for each service pass through a dedicated static IP. This way, you can create whitelisting rules in your Firewalls. This approach makes sure that the Inbenta Chat app is the only tool that is allowed to consume the designated webhooks.
• Use a webhook handshake with third party integration services. This ultimately leaves your system in charge of the execution of the transaction.
  • When Inbenta consumes a third party integrator’s webhook, the same security measures apply. This way, external integrators can use the Inbenta Chat app services to create a secure handshake.
  • Third party integrators can support other approaches, such as establishing VPN connections to your internal networks. Such approaches create a higher exposure of your internal network and are much less reliable. However, if you already rely on a third party entity to expose certain services externally, you can set the Inbenta Chat app to consume webhooks that your network does not host directly.

Webhook handshake

To make the handling of transaction by the Inbenta Chat Platform easy and flexible, webhooks become an abstraction layer that can connect to any external transactional service. This provides homogeneity in the handshake with the Chat app.

A webhook will consist of a POST HTTPS connection sent to a web application. Form data provides all the parameters that the transactional service behind the webhook requires. The webhook then implements the communication protocol with the transactional service. It collects the output of this service, then maps it into a simple structure that the Inbenta Chat app uses to process the result of the transaction automatically. This is illustrated by the following flowchart:

The above chart illustrates the flow that the Chat app follows once Inbenta NLU identifies that the user’s intent is to execute a transaction. The “Send Webhook Request” action step bundles together the HTTPS request and the webhook, and collects the webhook's response. If the format of the response is valid, and if the response returns a success state, then the transaction is confirmed to the end user.

Webhook Request Format

The Inbenta Chat app collects all necessary parameters and bundles them together with the session ID to create the request to the webhook application. It propagates all the parameters in the request's POST form data. 

All webhook requests follow this pattern:

https://webhooks.customer.com/flight-details/ 
[
    "inbenta_context": [
        "sessionId" => "4aqo58oca8sjr1n4bbcmlvv993"
    ],
    "parameterName1" => "variableValue1"
    "parameterName2" => "variableValue2"
    "parameterName3" => "variableValue3"
     ...
]

You can configure parameter names in your Chat app from the Knowledge > Action tab (This link opens the Inbenta Help Center. You need an Inbenta account to access it).

Example with Curl:

curl https://webhooks.customer.com/mywebhook -d 'inbenta_context[sessionId]=1234&parameter1=value1

Webhook Response Format

All webhook responses must follow a specific format to allow the Inbenta Chat app to process the result of the transaction automatically and return custom responses to the end user.

Webhook responses must return a JSON with three main attributes:

• Status: Success / Error. (mandatory)
• Raw Output: A list of parameters¹ and their new values to be captured. (optional)\ You can configure these optional parameters in your Chat app from the Knowledge > Action tab (This link opens the Inbenta Help Center. You need an Inbenta account to access it). Inbenta recommends to return output parameter names rather than variable names, because this allows Botmasters to change variable configuration without the need to update the webhook. However, the Engine also accepts variable names.
• Chat Response: A formatted response to be returned to end user. (mandatory)

¹ Important: When the webhook returns a parameter value, the API always tries to capture this value and store it within one of the variables of the instance, under the following rules:

1. First, the API looks for a matching output parameter name in the action configuration.
2. If the first step is unsuccessful, the API then looks for a matching variable name in the instance.
3. Finally, if the API found neither a matching output parameter name nor a matching variable name, it tracks a capture error in the Dashboards. The Chat conversation continues.

Success Response Format

{ 
    "status": "success",
    "raw_output": [ 
        { 
            "output_variable": "parameterName1", 
            "output_result": "VariableValue1" 
        }, 
        { 
            "output_variable": "parameterName2", 
            "output_result": "VariableValue2" 
        }, 
        { 
            "output_variable": "parameterNameN", 
            "output_result": "VariableValueN" 
        } 
    ], 
    "chatbot_response": "Transaction has been completed." 
}

Error Response Format

The status and message fields are mandatory. Optionally, the webhook can include and show a chatbot_response to give the end user some feedback about the error. The message field is only used for logging purposes. The end users never see it.

{
    "status": "error", 
    "message": "Internal booking service error" 
    "chatbot_response": "Sorry, there are no flights available for these dates" 
}

Webhook Example

One of your users wants to retrieve their flight information. The Inbenta Chat app's instruction is to collect the user e-mail address and the reference number provided when the ticket was purchased.

After it successfully collects the required parameters, the Chat app submits a request to the designated webhook like this:

https://webhooks.customer.com/flight-details/ 
{
    "inbenta_context": {
        "sessionId": "4aqo58oca8sjr1n4bbcmlvv993"
    },
    "e-mail" : "johnny5@novalabs.com"
    "reference-number" : "1234"
}

Example in Curl:

curl https://webhooks.customer.com/flight-details/ -d 
'inbenta_context[sessionId]=1234&email=johnny5@novalabs.com&transaction_ref=1234' 

The Chat app collects the two parameters and fires the request to the Webhook. This triggers a request to execute the transaction to your internal services, and returns the following response:

{
    "status": "success",
    "chatbot_response": "Your Flight INB1234 will depart at 13h45.",
    "raw_output": [
        {
            "output_variable": "NEXT_FLIGHT_NUMBER",
            "output_result": "INB1234"
        },
        {
            "output_variable": "NEXT_FLIGHT_DEPARTURE_TIME",
            "output_result": "13h45"
        },
        {
            "output_variable": "UserName",
            "output_result": "John Doe"
        }
    ]
}

The user receives the response as it is formatted in the chatbot_response object. However, the raw_output object provides relevant raw details that the Inbenta Chat app can keep in memory if you configure the Webhook accordingly. For example, the two variables UserName and UserType might be variables that you want to retain, to avoid having to request them again if the Chat app needs to carry out more transactions, or because the type of user defined obtains special treatment by the Chat app.

You can follow this transactional link process to securely streamline the handshake with other transactional services through other Webhooks. This simplifies the work of Chat managers and allows them to focus on providing the desired customer experience. Webhooks also provide a robust and durable layer that you or your external integration services can fully control. This way, you are not dependent on the Chat platform to keep the handshake methods synchronized with updates on your transactional services.

Using a webhook to capture Multiple-value variables

You can use a webhook to capture multiple values:

{
    "status": "success",
    "raw_output": [
        {
            "output_variable": "available_car_colors",
            "output_result": ["red", "green", "black", "purple"]
        }
    ],
    "chatbot_response": "Transaction has been completed."
}

Multiple values can only be captured if all sent values are captured. If one of them is not accepted by the variable restrictions, the variable value does not change. When a variable that allows multiple values does not have any captured values, the related dynamic list variable does not have the source values that it needs to perform value capture and display possible values as selectable options. Inbenta recommends that you add a default value to multiple values variables to avoid obtaining empty variables.

Using webhooks to reset variables

You can also use a webhook to reset a Chat variable:

{
    "raw_output": [ 
        { 
            "output_variable": "parameterName1", 
            "output_result": null 
        }
    ]
}

When you reset a variable, the Chat app will first try to capture its default value. If there is none, the variable value will be cleared.

You can also still use “raw_output” to capture variable values as before. Here is an example of how to reset and then capture different variables in the same webhook:

{
    "raw_output": [ 
        { 
            "output_variable": "parameterName1", 
            "output_result": null 
        },
        { 
            "output_variable": "parameterName2", 
            "output_result": "newValue" 
        },
        { 
            "output_variable": "parameterName3", 
            "output_result": "newValue2" 
        }
    ]
}

Webhook timeout limit and proxies

Webhook timeouts

There are two types of timeouts: controlled timeouts and uncontrolled timeouts. A controlled timeout occurs when the webhook’s server itself recognizes the process is taking too long to process a request and breaks the connection. In this case:

• The webhook returns either a 408 Request Timeout or a 504 Gateway Timeout error, and
• The Chat API returns the personalized webhook-bad-request answer defined in the Chat instance’s Knowledge Base > Actions screen.

When the webhook takes longer than 30 seconds, which is the standard webhook response timeout limit, this is called an uncontrolled timeout. This means that the Chat API considers the webhook status to be “failed” after 30 seconds of execution time.

In this case:

• Another service breaks the connection.
• The Chat API cannot return the personalized webhook-bad-request answer defined in the Chat instance because the gateway cuts it off.

Inbenta therefore recommends that you set webhooks to time out sooner to ensure that the Chat API can return a message to the user in case of a timeout.

Webhook timeouts in combination with a proxy

When you use a proxy, the webhook response timeout is reduced to 3 seconds. To use a proxy, you need to enable the “Use Proxy” setting under Settings > General Settings > Webhooks global configuration in your Chat instance. For more information, see Webhooks global configuration in the Inbenta Help Center.

Webhook restrictions

The following restrictions apply to webhooks:

• Webhook payload size is limited to 1MB.
• Follow redirects are not supported.
• Self-signed certificates are not supported.

Special considerations using AWS

The default Amazon API gateway endpoints are not accepted in webhooks. If your webhook has an URL similar to the following:

https://{XXXXX}.execute-api.{REGION}.amazonaws.com{/YYYYY….}

You have to setup a custom domain name using Amazon Route 53, so your webhook URL looks like this:

yourClientDomain.com{/YYYYY....}