Creating a Webhook from scratch for Companies

To create a Webhook from scratch as a Company, you first have to navigate to the Webhook Builder, then choose "Create from Scratch". Below, we'll explore the following fields, which you'll see when you enter the "Webhook Creation" screen:

Basic Data


In this section, you must enter the name of the Webhook. In this case, it's useful to name the webhook in such a way that the purpose of the webhook is not left up to interpretation.

Then, you will have to pick your preferred type of HTTP request. We support many kinds of HTTP request methods, such as GET, POST, PUT, PATCH, DELETE and more. The next step is to enter the URL for the API Endpoint that you will be using for the webhook.

In the current iteration of the Webhook Builder, the only Response Type that we support is JSON. We expect to add support for XML in a future iteration. The same holds true for Conversation Execution, where we currently have support for Synchronous Conversation Execution, and we plan to add support for Asynchronous Conversation Execution in the near future. Synchronous Conversation Execution means that the conversation flow stops until the Webhook either replies or times out. Asynchronous Conversation Execution means that the conversation flow will keep running. 

The last thing you will need to do here is to choose the time out of the Webhook (how long the bot will wait for the external service to respond). The default setting is 5 seconds.


In this field, we ask you to enter the type of authentication that the API connected to your URL Endpoint uses. We currently offer three types of authentication:

  • No authentication means that there will be no authentication of the API connected to your URL endpoint. In this case, there's no authentication information to put in.
  • Basic authentication is a simple form of authentication that requires a username and a password for the API to be inserted into the fields. 
  • Bearer authentication means that the authentication of the API is based on the bearer token system. This means that there will need to be a security token inserted into the field. 


Headers are responsible for carrying relevant data back and forth. This information can be anything from the type of browser that the user is using to how long you want to keep the connection active. In this field, you can include the information that you deem relevant for the data exchange. 


Parameters, or query strings, are a part of the URL that you've selected as your URL Endpoint. With this function, you can either choose to put the parameters directly into the URL Endpoint in Basic Data, or you can enter the parameters into this field. 


Context Values are only available here when there are {{curly bracket values}} in the URL Endpoint. They can be used to render as specific subdomains when using the WHT for different environments, tenants, accounts, etc.


With most HTTP requests, you will be sending a body along with the request. This is typically the content that you wish to send to the third-party server. The sample JSON below lists all the different variables that you can use to send Bot User or conversation metadata in the message body of the request:

"lastName": {% if fb is defined %}"{{fb.lastName}}"{% else %}{}{% endif %}, //Only available in FB channel
"replyData": {% if certainly.replyData is defined %}{{certainly.replyData|tojson}}{% else %}{}{% endif %}, //Validated Response in a Collector Module
"sessionId": {{certainly.sessionId}}, //Unique ID for the conversation
"attachedMedia": "{{certainly.attachedMedia}}", //Empty value for now
"direction": "{{certainly.direction}}", //"in" or "out". Always "in" for now. "in" if it is a message from the end user to the bot, and "out" if it is a message from the bot to the end user
"reply": "{{certainly.reply}}", //Raw user response 
"extractedData": {% if certainly.extractedData is defined %}{{certainly.extractedData|tojson}}{% else %}{}{% endif %}, //JSON with previously validated responses
"botId": "{{certainly.botId}}", //Bot UUID
"botDeploymentId": "{{certainly.botDeploymentId}}", //Bot deployment UUID
"firstName": {% if fb is defined %}"{{fb.firstName}}"{% else %}{}{% endif %}, //Only available in FB channel
"customVariables": {% if certainly.customVariables is defined %}{{certainly.customVariables|tojson}}{% else %}{}{% endif %}, //Previously generated Custom Variables
"moduleId": {{certainly.moduleId}}, //ID of the current module
"to": "{{}}", //Channel ID
"from": "{{certainly.from}}", //Bot User External ID
"botTrainedModelId": "{{certainly.botTrainedModelId}}" //The UUID string for the AI model key

Run Webhook

Once you've completed all the preceding steps and filled in the required fields, it's time to run your Webhook. This is useful as it allows you to check the result of the Webhook Response, as well as define and review the Custom Variables you extract.

Custom Variables

In this field, it is possible to define one or more Custom Variables without needing to run the Webhook. The Custom Variable values are parsed from the Webhook Response using the Jinja2 path added in the 'Response Mapper' field.

Was this article helpful?

0 out of 0 found this helpful
Have more questions? Submit a request

Comments (0 comments)

Please sign in to leave a comment.