What are webhooks?¶

A webhook allows your bot in VisualMaker to receive information from other services or systems. Think of webhooks as "messengers" that deliver data to your bot. While HTTP requests let your bot fetch data, webhooks allow your bot to receive data without making a request.

Prerequisite¶

Premium subscription: Webhooks require the use of actions exclusive to VisualMaker’s premium subscription.

How do webhooks work?¶

When an external service wants to send information to your bot, it uses a webhook. This involves an HTTP request to the VisualMaker server, including data and parameters for the bot to process.

Webhooks send external data to your bot.
The way to receive this data is through the buttons and commands of your bot, using the action Receive parameters.
The webhook server URL is: https://visualmaker.net/webhook
Requests can be sent as GET or POST, using formats like JSON, params, or data.

Webhook key¶

To use webhooks, you need your webhook key, which is unique to each bot.

Go to VisualMaker.
Navigate to 🖥 Bots → 📜 My Bots.
Select your bot and choose 🌐 Webhook key.
Click 👁 Show key 👁 to view it.

IMPORTANT

Keep your webhook key secure. If someone else obtains it, they could control your bot!

Steps to use webhooks in your bot¶

To receive a webhook in your bot:

Create a Command or Button

Set up the button or command that will be executed when the webhook is received. This will handle the incoming data from the external service.
Add the "Receive parameters" action

Navigate to the button or command you just created (the one that will handle the external data). Add an action of type Receive parameters, ideally as the first action in the sequence.
Configure the webhook in the external service

Inform the external service sending the webhook about what it needs to send to your bot. Use the following format to include the data in the webhook URL:
```
https://visualmaker.net/webhook?key=YOUR_WEBHOOK_KEY&run=/YOUR_COMMAND_OR_BUTTON&user_id=USER_ID&param1=A_PARAMETER&param2=ANOTHER_PARAMETER
```
You just have to replace the data that is in capital letters with your own data.
Receive the data in your bot

Retrieve the data in your bot using the Receive parameters action added in step 2. Access the parameters using their respective identifiers, as follows:
```
{#ReceiveParametersActionID.param1#}: To retrieve parameter 1.
{#ReceiveParametersActionID.param2#}: To retrieve parameter 2.
```
Repeat this process for additional parameters as needed.
Use the received data in your bot

Utilize the data received from the webhook wherever needed within your bot, such as for processing, messaging, or triggering further actions.

Parameters for webhooks¶

key: Your webhook key.
run: The button or command to execute (e.g., Balance or /my_command).
user_id: The Telegram ID of the user for whom the button or command will be executed.
param(num): (Optional) Additional data sent by the webhook to your bot, such as names, amounts, or currency types.
More information
- Replace (num) with the parameter's position, starting at 1.
- Receive these using the Receive parameters action within the button or command set using the run parameter.
- If parameters are sent as JSON, they retain their original data type. However, if sent via params or data, they are treated as strings, and you may need to convert them to the desired type using appropriate functions.

Practical example: Integrating an External Payment Processor¶

Imagine you want to configure your bot to receive notifications from an external payment processor whenever someone makes a deposit. Follow these steps:

Step 1: Create the command¶

Open your bot and select 🛠 Edit.
Create a new command by clicking on ✳️ New Button | Command.
Name the command /payment_received.
Make it invisible to users:
- Go back to the command's options and click Hide 👁.
- This ensures that only the external webhook can execute it.

Step 2: Add the necessary actions¶

Go to the /payment_received command and access its actions menu by clicking on Actions 🌟.
Add these three actions in order:

1. Receive parameters from the webhook¶
- Add an action of type Receive parameters.
- Activate it by clicking ✅ Activate.
- Copy the Action ID displayed (e.g., #XYZ12#); you’ll use it later.
2. Update the user's balance¶
- Add an action of type Change variable.
- Configure it by clicking Configure 🛠:
  - Click 💠 Select variable 💠 and type balance.
  - Choose the option 🔺 Increase 🔺.
  - Use the Action ID you copied earlier to define the amount to increase. Append .param1 at the end, like this: #XYZ12.param1#.
- Activate the action by clicking ✅ Activate.
3. Notify the user¶
- Add an action of type Send message.
- Configure it by clicking Configure 🛠:
  - Write a message for the user, for example:
```
You have received {#XYZ12.param1#} {#XYZ12.param2#}.
```
    Note: Replace XYZ12 with the ID of the Receive parameters action.
- Activate the action by clicking ✅ Activate.

Step 3: Configure the payment service¶

In the external payment processor, set up the webhook with the following URL:

https://visualmaker.net/webhook?key=YOUR_WEBHOOK_KEY&run=/payment_received&user_id=user_id&param1=deposit_amount&param2=currency_used

Explanation of parameters:¶

key: Your webhook key.
run: Specifies which command to execute upon receiving the webhook (/payment_received).
user_id: The ID of the user who made the payment.
param1: The deposited amount.
param2: The currency used (e.g., USDT, TON, etc.).

Expected outcome¶

Whenever someone makes a payment:

The payment processor will send the data to your bot via the webhook.
The bot will execute the /payment_received command.
The Receive parameters action will capture the sent data.
The user's balance will be automatically updated with the received amount.
The user will receive a message like:
```
You have received 3 TON.
```

Server response¶

When VisualMaker receives a webhook, it responds with:

status: 200 if everything is okay. Other numbers indicate errors.
message: "ok" if successful. An error description otherwise.

Example response: {"status": 200, "message": "ok"}

Helpful tips¶

Webhooks don’t trigger buttons or commands: They directly execute the actions they contain. To "press" a button or command, combine the webhook with the Run button action.
Webhooks execute hidden buttons and commands: They can execute buttons and commands even if hidden.

Webhooks are perfect for advanced integrations, such as payment systems, notification services, or any scenario where an external system needs to interact with your bot automatically.