Skip to content

What are webhooks?

Webhooks are a feature in VisualMaker that allows your bot to receive data from external sources. Put simply, while HTTP requests allow you to request data from an external page, webhooks enable your bot to receive data through HTTP requests sent to the VisualMaker server. In other words, HTTP requests send, and webhooks receive.

Webhook key

To receive webhooks in your bot, you'll need your webhook key, which is unique to each bot.

Locate it on VisualMaker, by going to 🖥 Bots, then 📜 My bots, selecting the bot you want to receive the webhook for, and then choosing 🌐 Webhook key. If you click on 👁 Show key 👁, you'll see your key.

IMPORTANT

Safeguard your webhook key carefully, as anyone with it can gain control over your bot.

How to use webhooks?

To use webhooks, you need to have basic knowledge of how HTTP requests work.

To receive a webhook, you need to make a request to the VisualMaker server, specifying your webhook key and other parameters.

Requests can be either GET or POST, and can be sent in JSON, params, or data format.

The VisualMaker server that listens to webhooks is: https://visualmaker.net/webhook

Parameters that can be used

  • key: Your webhook key, unique to each bot.
  • run: Button or command to execute within your bot, if it's a command, it must start with / or !.
  • user_id: Telegram ID of the user to whom the button or command will be executed.
  • param(num) (optional): Parameters to send to your bot upon executing the button or command. Replace (num) with the parameter position, starting from 1. Receive them with the Receive Parameters action. If parameters are sent as JSON, they will retain their corresponding data type. However, if they are sent using params or data, they will be sent as plain text (string), so you need to convert them to their data type using the appropriate function.

Server response

Whenever a webhook is received on the VisualMaker server, it will return a response, either to indicate that the webhook has been received correctly or to show an error. It will return:

  • status: It can be 200 to indicate that everything went well, or another value if an error occurred.
  • message: It can be "ok" to indicate that everything went well, or if the webhook was not received, you will see a message of what happened.

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

Information

Webhooks will execute buttons and commands even if they are hidden.

Webhooks do not press the button or command, but execute the actions it contains. This is to avoid conflicts with the editor mode. If you need to press a button after receiving a webhook, combine it with the action Execute button.

Each received webhook consumes webhook resources, which renew every month. These can be increased by upgrading your subscription in VisualMaker or by purchasing packages for a specific bot, which never expire. To do this, go to VisualMaker ➡️ 🖥 Bots ➡️ 📜 My bots, select your bot, then select 📦 Extra packages, and finally select 📡 Webhook.

Example

Suppose you want to integrate an external payment processor into your bot, and when a user makes a deposit, you want the processor to send a notification to your bot with the details of the deposit made, so you can process it.

That's when you would need to use webhooks. First, you need to create a button or command in your bot, which will be executed when the webhook is received.

For this example, we'll create a command called /payment_received and set it to hidden, as we don't want another user of the bot to execute it.

Inside, we create an action of type Receive parameters, and in a real situation, you would create another one of type Save to variable to modify the user's balance. But in this example, we'll simply use one of type Send message to display the parameters received, saving a message that shows the content of param1 and param2.

Then, go to the payment processor and tell it that when a deposit is received, it should send a webhook to the following URL: https://visualmaker.net/webhook?key=12345678-1234-1234-1234-123456789012&run=/payment_received&user_id={user_id}&param1={amount}&param2={currency}

The parameters must be stored according to the specifications of the external service, each one may be different from the others.

So, every time a deposit is made in your bot, the payment processor will send a webhook to you, and you'll process it with your /payment_received command.