Webhooks
Last updated
Last updated
Webhooks are a simple way for one application to notify another about an event in real time.
Suppose you create a bot that automatically processes user orders on an e-commerce site. This bot has the capability to use webhooks to notify other systems about key events. Here's how it works:
Creating a Webhook: You create a webhook for some important event, for example, the completion of order processing. During the creation process, you specify a URL where notification should be sent when a certain event occurs.
Event Occurs: During a dialogue with Suvvy, the user places an order, and Suvvy successfully processes it. After all computations and operations are complete, Suvvy realizes it's time to notify other systems about this.
Sending a Webhook: Immediately after successfully completing order processing, Suvvy sends an HTTP request to the specified URL, containing information about the order—its status, number, details, etc. This request is called a webhook.
Processing on the Recipient Side: Another system—such as a delivery service or CRM—receives this request (webhook) and uses it to perform further actions. Suppose CRM receives a notification and updates customer data about their new order, or the delivery service begins preparing the package for shipping.
Thus, the use of webhooks in Suvvy allows easy and automatic integration with other applications and services, eliminating the need for constant status checks and enabling immediate response to occurred events. This makes the interaction between systems faster, more accurate, and more convenient.
Now let's delve into the technical features of each stage in more detail.
Webhooks are created through the Actions section within the bot settings:
Action Name - simply a name for display in the list.
Function Name - this is the name of the function that the LLM model will see. This name is indicated in English without spaces. The name should reflect the general meaning of the action.
Function Description - a more detailed description of the meaning of the action. Based on this description, Suvvy will understand when it needs to be invoked.
Error Message - a message that Suvvy will receive from the action if an error returns on the webhook side. It can be empty, in which case Suvvy will receive the error text from the URL to which the webhook is sent.
Action Arguments - these are variables that need to be filled by the bot, and which can be selected later when adding steps/calling specific requests.
For example, you use an API call to get order data using the client's phone and birth date. You can set these variables here immediately, and the bot will understand that they need to be collected from the client before the API call. When adding steps, these variables will be filled with specific values, and they can be substituted where needed.
Action Constants - these are specific constant values that can be set fixed and invoked in all subsequent steps.
For example, you need to make an API call to a service. When calling this service, a specific token of yours is used, which needs to be passed in several steps. Using constants, you can set this token once and then choose it without the need to specify it each time at each step separately.
Within Actions, you can call a sequence of actions using different types of calls, so it's called steps.
When adding a step, you can choose one of three options: webhook call, subordinate bot call, or table call. We will discuss the second and third options in the following sections; in this case, we are interested in the webhook:
When chosen, a step form will open:
Name - name for display in the list of steps.
URL - the address to which the request will be sent is specified here. This can be both an IP address and a domain name, for example, https://192.168.34.12 or https://test.ru (here will be some necessary address of yours).
Request Method - methods of the sent request. This method must be provided by the end side. More about methods can be found here.
Parameters to be Passed in the URL - these are the parameters usually passed in the address after the ? mark.
For example:
https://192.168.34.12/CRM?phone=79112345678&date=09012024
Where phone and date are parameters
In the step form, this example will look like this:
But in this case, we passed fixed values. How do you make it so that these quantities are variable and unique for each client/dialogue? For this, variables are used.
We specified variables in the previous step when we added them in the action form, now we just need to select them using the + button. For the example described above, when we need to specify variable parameters, we do it like this:
At the same time, even though we recommend making detailed descriptions, the bot does not need additional instructions on what parameters to request from the client; it will understand that by itself. Therefore, it's better to choose understandable variable names.
Variables can also be specified in the URL when they are not explicitly parameters, for example, like this:
Where phone will automatically be replaced with the phone sent by the client.
Authorization information is often passed in the request headers.
These are more static parameters, but sometimes dynamic parameters, such as an encryption key obtained in the previous step, can be passed.
When sending POST requests, a field appears where the request body is specified.
We have implemented two body types - plain text and JSON.
To avoid errors when sending, certain syntax rules must be followed. JSON elements should be in quotes. Variables are also selected by clicking +. In the example described above, the request body will look like this:
Remember to use quotes when using JSON, even for highlighting variables.
You can specify status codes to which the bot will respond. By default, code 200 is set, which is the successful return code. In the case of failure, the bot simply does not receive any response - an empty string. You can remove the filter on status codes - and then it will see all statuses and all errors that return to it and will pass them to the client.
Since, as mentioned earlier, we can transmit a sequence of steps, including in the form of webhooks at one time, there is a setting that determines what we transmit to the bot in response:
All - transmit all responses from each step
Only the first - only the response from the first step
Only the last - only the response from the last step
By default, the response of the last step is set, which seems logical. However, of course, there are scenarios where we can transmit information from the first step and further perform a series of service actions, the response from which we do not transmit to the client, for example, when we just notify external systems of some trigger.
There is another setting that allows you to regulate the text of the response returned to the bot in case of an error.
For example, if we don’t want to pass on the text of the returned error, as it may contain technical details not needed by the client, we can standardize the text returned to the bot, which it will pass to the client through this field:
