Webhooks

Introduction

Webhooks are automated triggers initiated between two applications on occurrence of a pre-defined event. In our case, if you choose to have your business logic in any external server you can opt for webhooks as the development platform. You need to make sure that the external server is publicly accessible to ConvoKraft through a REST API. To execute the business logic, the configured Webhook URL will be hit by ConvoKraft at the corresponding invocation points during action execution.

The Webhook server should comply with the below request and response formats for proper functioning of the ConvoKraft bot.

Request Format

ConvoKraft sends the request in the following format to the configured Webhook URL.

    

        
copy
        

            

        
    
    

         {
"todo": "prompt || execute || fallback || button",
"bot" : "",
"action" : "",
"button_id" : "",
"environment" : "development || production"
"params":{
},
"userInput" : "",
"previousParam" : "",
"user" : {},
"org" : {},
"broadcast" : {},
"cache" : {},
"sessionData" : {}
"clientData" : {} 
}
    

Response Format

ConvoKraft expects the response to be in the following format from the Webhook URL, so that it understands and conveys the intended response to the user. ConvoKraft supports multiple response types for displaying content in various formats. You must ensure to follow the defined standards when configuring responses. For more information on response structures, refer to this section.

Case 1: When an input param has to be prompted to the user

    

        
copy
        

            

        
    
    

         {
"status" : "prompt",
    "prompt" : {
        "param_name" : "leave_type",
        "options":[  
                    { "id" : "111" ,"label" : "", "image" : "image_url"},
                    {"id" : "112" ,"label" :"" ,"image" : "image_url"}
        ],
"buttons" : []
    },
    "message" : "You don't have enough casual leaves. Please choose some other leave type.",
    "data" : {}  
}
    

Case 2: When an output message has to be displayed to the user

    

        
copy
        

            

        
    
    

         {
    "status" : "execution",
    "message":"Please check your screen.",
    "card":[],
    "data":{},
    "broadcast":{},
    "trigger":{},
    "followup" : {}    
}
    

There are a few restrictions to be considered with the responses received from the Webhook URLs, such as :

• The maximum size of the response is 100 KB.
• The maximum duration of request timeout is 5 seconds.

If the response doesn’t comply with the above guidelines, a failure message will be sent as a response to the user.

Securing Webhook Calls

The Webhook requests can be secured so that it can be validated by the Webhook server whether the request is originated from ConvoKraft, to avoid processing untrusted requests. ConvoKraft uses Digital Signature Algorithm(DSA) Cryptosystem to generate security keys, which has to be used by the Webhook server to validate the request.

Security validation flow

1. Once you opt to secure your webhook calls while choosing the development platform, ConvoKraft auto-generates a private key and a public key based on the DSA Cryptosystem. Both these keys are encrypted will be stored in ConvoKraft’s servers and only the public key will be exposed to the developer in the Catalyst console.

2. While sending a request to the Webhook server, ConvoKraft generates a digital signature using the stored private key and sends the signature in the request header X-CONVOKRAFT-SIGNATURE. When user types a message in the chat window, the message is encrypted with the private key and sent in the request body to the webhook server along with the digital signature in the header.

3. When the Webhook server receives this message, it makes a comparison of the received digital signature in the request and the original signature created using the encrypted public key. If there is a discrepancy found, then that means the message has been tampered.

Implementation

Once you create a bot, you can choose webhooks as the development platform and follow the below steps :

1. Enter the webhook URL of your external server in which the business logic code resides. On execution of the configured actions of the bot, this URL will be accessed.

   

2. You can choose to invoke the webhook URL either at the end of every user message in the conversation or whenever a particular context of the conversation ends.

   

3. Once bot creation is done, you will be able to view the Bots details page which lists the crucial information of your ConvoKraft bot.

   To view the generated public key, click the Show key button on the Bots details page.

   

   Upon clicking the Show key option, the Security Key pop up will display the public key.

   

   This public key will be used in the development environment immediately. It will be used in the production environment, once you deploy your Catalyst project.