Webhook can be used by developers to create a back-end logic for your bots. For instance webhook can calculate some data on your own servers and inject it into your bot's logic.

This guide explains how to setup and use webhook and how it differs from HTTP request block.

How webhook works in Aimylogic

Webhook is a transparent logic for your bot. Once the bot steps into some screen, it sends a POST request to your webhook with all variables currently available in scenario, and waits for a response. A response can contain a set of variables that should be propagated to the bot. Your bot saves these variables and starts to execute blocks on the current screen.

Thus you are able to add/change/remove any variables in your bot during it's work, and implement any logic on your own servers with any programming languages.

Webhook Action

You have to define action on every scenario's screen where you'd like to propagate some data from your webhook. Action is an arbitrary string that identifies the operation your webhook has to do. Thus you webhook can understand the screen from where the bot sent the request, and what variables it needs.

You can use the same action for different screens in your scenario.

How to setup a webhook

Please find a section named "Webhook settings" on your bot's settings page.

Here you have to define a public URL of your webhook. It has to accept a POST requests and respond with appropriate format (please see below).

Once you've setup a webhook, you have to enable it on some screens of your scenario. Once the bot steps into such screen, it sends a POST request to your webhook and waits for response, saves all data from response to variables, and starts to execute blocks on the screen. Thus it can use received variables as usual - in text output, conditions, HTTP requests and etc.

Webhook for tests

You are also able to define URL for tests. Thus your bot will send requests to this testing back-end while you test a bot via the test widget. This is very useful for rapid development of the webhook logic, because it doesn't affect a production one and your webhook can be run even on your local machine for debugging purposes using ngrok for instance.

Webhook API

Request format

On every screen with enabled webhook action your bot sends a POST request to your webhook (or test webhook). The body of such request contains a JSON with an action and a full set of currently available variables (including system ones). For example

{
"action": "my_action",
"queryText": "hello",
"userId": "1234567890",
"channelId": "0000000000000000",
"channelType": "telegram",
"lastSeen": 12,
"rawRequest": {"message": {...}},
"variable1": 50,
"variable2": "some string"
}


Response format

Your webhook should response with 200 OK status code and JSON body that contains a set of variables you'd like to propagate to the bot. For example

{
"name": "Bob",
"data": {
"age": 30,
"website": "http://example.com"
}
}


In this example a webhook responded with JSON that contains name and data variables. You can return variables with any types (string, number, boolean, array or object).

How webhook differs from HTTP Request block

You could use HTTP Request block every time your bot needs to send some data to your back-end and receive some data in response. But webhook brings some advantages over this approach if you need to send such request more than one time in your scenario.

You do not need to clone the same HTTP Request block multiple times, thus your scenario becomes more compact and readable.
Webhook sends a full list of currently available variables on the same URL you've defined in bot's settings, so you don't have to configure a request each time and it's easy to maintain such an URL.
Webhook has a fixed format of request and response, thus it's easy to maintain such requests, and bot will automatically clone all variables from response.
You need only a one click to enable or disable webhook on any screen of your scenario, thus you don't have to re-design full scenario each time you need to call your back-end.
You can use test webhook to develop a back-end code locally without affecting a public version of your bot.

When to use Webhook instead of HTTP Request block

If your bot needs to store or obtain some data from your back-end more than once per scenario, it's much easier to use webhook instead of multiple HTTP Request blocks. It will also simplify a webhook development process once Aimylogic provides a way to separate test webhook endpoint from the production one.

When you do not need to use Webhook

If there is only a single screen in your scenario where your bot needs to sore or obtain some data from your back-end, it may be faster to use a single HTTP Request block instead of webhook.

How to develop a Webhook

You can use any programming language and any SaaS platform or provider to deploy your webhook to the public. We've prepared some webhook templates to simplify this process.

Node JS
Python

Where to deploy your Webhook

Once you are ready to publish your webhook, you have to pick some provider to host your webhook code and obtain a public URL. Here are some options for a free hosting for your webhook.

Heroku

heroku.com provides a free plan for any server applications. You can deploy your webhook code to Heroku with a few clicks and a single configuration file.

Webtask

If you develop your webhook using Node JS, and your webhook is not a very complicated and doesn't require a lot of resources, webtask.io could provide a free hosting for your webhook code.
Was this article helpful?
Thank you!