Webhooks

Transactions Architecture

The Inbenta Chatbot 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.

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 Chatbot 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 Chatbot 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 Chatbot 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 Chatbot to consume webhooks that your network does not host directly.

Webhook handshake

To make the handling of transaction by the Inbenta Chatbot 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 chatbot.

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 Chatbot uses to process the result of the transaction automatically. This is illustrated by the following flowchart:

The above chart illustrates the flow that the chatbot 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 Chatbot collects all necessary parameters and bundles them together with contextual information (below, the session ID and token) 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",
        "sessionToken" => "0YmJjbWx2djk5MyJ9.chnAaDhc4HSQGRqleyeMOrutODQj1UW6l4hliuKmBnw"
    ],
    "formFieldName1" => "variableValue1"
    "formFieldName2" => "variableValue2"
    "formFieldName3" => "variableValue3"
     ...
]

Example with Curl:

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

Webhook Response Format

All webhook responses must follow a specific format to allow the Inbenta Chatbot 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.
  • Raw Output: A list of variables1 and their new values to be captured. (optional)
  • Chatbot Response: A formatted response to be returned to end user.

1 Important: Remember that the variable names returned in raw_output must match the names of existing variables within your instance. If the names do not match, the Engine will be unable to capture and store the variable values returned by the webhook.

Success Response Format

{ 
    "status": "success",
    "raw_output": [ 
        { 
            "output_variable": "VariableName1", 
            "output_result": "VariableValue1" 
        }, 
        { 
            "output_variable": "VariableName2", 
            "output_result": "VariableValue2" 
        }, 
        { 
            "output_variable": "VariableNameN", 
            "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 Chatbot's instruction is to collect the user e-mail address and the reference number provided when the ticket was purchased.

After it successfullly collects the required parameters, the Chatbot submits a request to the designated webhook like this:

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

Example in Curl:

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

The chatbot 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 <b>13h45</b>.",
    "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 Chatbot 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 Chatbot needs to carry out more transactions, or because the type of user defined obtains special treatment by the chatbot.

You can follow this transactional link process to securely streamline the handshake with other transactional services through other Webhooks. This simplifies the work of Chatbot 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 Chatbot 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.