Saltar a contenido

¿Qué son los webhooks?

Los webhooks son una característica en VisualMaker que posibilita que tu bot reciba datos de fuentes externas. De manera simple, mientras las peticiones HTTP te permiten solicitar datos de una página externa, los webhooks permiten que tu bot reciba datos a través de solicitudes HTTP enviadas al servidor de VisualMaker. Dicho de otra forma, las peticiones HTTP envían, los webhook reciben.

Llave webhook

Para recibir webhooks en tu bot necesitarás tu llave webhook, la cual es única para cada bot.

Localízala en VisualMaker, dirigiéndote a 🖥 Bots, después a 📜 Mis bots, selecciona el bot en el que quieras recibir el webhook, y selecciona 🌐 Llave webhook, si haces click en 👁 Mostrar llave 👁 verás tu llave.

IMPORTANTE

Guarda tu llave webhook cuidadosamente, ya que cualquiera que la tenga puede tener control sobre tu bot.

¿Cómo utilizar los webhooks?

Para utilizar los webhook necesitas tener conocimientos básicos de como funcionan las peticiones HTTP.

Para recibir un webhook, debes realizar una petición al servidor de VisualMaker, especificando tu llave webhook y otros parámetros.

Las peticiones pueden ser tanto GET como POST, y pueden ser enviadas ya sea en formato JSON, params o data.

El servidor de VisualMaker que escucha los webhooks es: https://visualmaker.net/webhook

Parámetros que pueden ser usados

  • key: Tu llave webhook, es única para cada bot.
  • run: Botón o comando a ejecutar dentro de tu bot, si es un comando debe comenzar por / o !.
  • user_id: ID de Telegram del usuario al cual se le ejecutará el botón o comando.
  • param(num) (opcional): Los parámetros a enviar a tu bot, al ejecutar el botón o comando. Reemplaza (num) por la posición del parámetro, empezando por 1. Recíbelos con la acción Recibir parámetros. Si los parámetros son enviados como JSON, conservarán su tipo de dato correspondiente, en cambio, si son enviados mediante params o data, serán enviados en formato de texto (string), por lo que deberás convertirlos a su tipo de dato usando la función que corresponda.

Respuestas del servidor

Cada vez que se reciba un webhook en el servidor de VisualMaker, este devolverá una respuesta, ya sea para indicar que el webhook ha sido recibido correctamente o para mostrar un error. Devolverá lo siguiente:

  • status: Puede ser 200 para indicar que todo fue bien, u otro si ocurre algún error.
  • message: Puede ser "ok" para indicar que todo fue bien, o si el webhook no fue recibido aquí verás un mensaje de lo ocurrido.

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

Información

Los webhook ejecutarán botones y comandos incluso si están ocultos.

Los webhooks no pulsan el botón o comando, sino que ejecutan las acciones que contenga, esto es para evitar conflictos con el modo editor. Si necesitas pulsar un botón después de recibir un webhook, combínalo con la acción Ejecutar botón.

Cada webhook recibido consume recursos de webhook, los cuales se renuevan cada mes, estos pueden ser incrementados actualizando tu suscripción en VisualMaker, o comprando paquetes para un bot en especifico, los cuales no vencen nunca, para ello ve a VisualMaker ➡️ 🖥 Bots ➡️ 📜 Mis bots, selecciona tu bot, luego selecciona 📦 Paquetes extras, y por último selecciona 📡 Webhook.

Ejemplo

Supongamos que quieres integrar en tu bot un procesador de pagos externo, y quieres que cuando un usuario realice un depósito, el procesador envíe a tu bot una notificación con los detalles del depósito realizado, para de esa forma poder procesarlo.

Ahí es cuando necesitarías hacer uso de los webhooks, primeramente deberás crear un botón o comando en tu bot, el cuál será ejecutado cuando se envíe el webhook.

Para este ejemplo crearemos un comando llamado /pago_recibido, y lo pondremos oculto, ya que no queremos que otro usuario del bot lo ejecute.

Dentro creamos una acción de tipo Recibir parámetros, y en una situación real crearías otra de tipo Guardar en variable para modificar el balance del usuario, pero en este ejemplo simplemente usaremos una de tipo Enviar mensaje para mostrar los parámetros que se recibieron sin más, en ella guardamos un mensaje que muestre el contenido de param1 y param2.

Entonces, vamos al procesador de pagos y le decimos que queremos que cuando se reciba un depósito, que nos envíe un webhook a la siguiente URL: https://visualmaker.net/webhook?key=12345678-1234-1234-1234-123456789012&run=/pago_recibido&user_id={user_id}&param1={amount}&param2={currency}

Los parámetros deben ser guardados según las especificaciones del servicio externo, cada uno puede ser diferente al resto.

Entonces, cada vez que se realice un depósito en tu bot, el procesador de pagos te enviará un webhook, y tu lo procesarás con tu comando /pago_recibido.