Webhook

Introducción

Webhook es una box que te permite enviar una petición HTTP a un servidor, para notificar cuando ocurre algo de interés, o bien, para solicitar información. Para comprender el funcionamiento, deberás estar familiarizado con los mensajes HTTP.

Los mensajes HTTP son los medios por los cuales se intercambian datos entre servidores y clientes. Hay dos tipos de mensajes: las peticiones o requests, que son los mensajes enviados inicialmente por el cliente al servidor para pedir el inicio de una acción u obtener cierta información; y respuestas o responses, que son las respuestas del servidor a las peticiones.

Método

Puedes seleccionar entre los métodos más tradicionales: GET, POST, PUT, DELETE y HEAD.

URL

Debes indicar una URL hacia la cual se dirigirá tu petición. Puedes utilizar una variable total o parcialmente. Ejemplos válidos:

https://myurl.com/get-client   //  Texto puro

https://myurl.com/{{my_endpoint}} //  Donde my_endpoint=’get-client’

{{my_url}} // Donde my_url = ‘https://myurl.com/get-client’

Importante: el texto resultante siempre debe comenzar con http:// ó https://

Parámetros del Query String

Se denomina Query string a la información adicional que podemos enviar junto con la URL. Todo lo que se encuentra a continuación del signo de interrogación (?) en una URL, se conoce como Query String. Ej.:

https://myurl.com/get-client?lastname=perez&name=pablo

Se conoce como parámetro a cada par clave=valor (ej.: lastname=perez), los parámetros se separan con el signo &.

En la box de webhook, no necesitas agregar los parámetros a la URL, sino que puedes cargarlos en la sección Parámetros del Query String del sidebar de edición. Allí debes cargar la clave y el valor de cada parámetro que desees agregar a tu petición. Puedes utilizar variables tanto en la clave como en el valor.

Headers

Debes cargar la clave y el valor de cada header que desees agregar a tu petición en la sección Headers del sidebar de edición. Puedes utilizar variables tanto en la clave como en el valor. Aquellos headers que en su clave o valor sean nulos, no serán incluidos.

Body

Puedes agregar un body a tu petición en la sección Body del sidebar de edición. Debes utilizar el formato JSON, encerrando entre comillas dobles (“) tanto los nombres de las propiedades como aquellos valores alfanuméricos. Los valores numéricos no necesitan encerrarse entre comillas. Puedes insertar variables en el body, independientemente de que el nombre insertado sea una variable propiamente dicha, un array o un objeto. Los nombres de las variables no deben encerrarse entre comillas. Ejemplo:

Teniendo que: 
dni_user = 12345678
name_user= ‘Pedro Perez’
likes = [‘tennis’, ‘basketball’, ‘running’]
address = { street: ‘342 Park Av.’, city: ‘New York’}


El Body resultante será
{
“dni”: 12345678,
“nombre”: “Pedro Perez”,
“dirección”: {“Street”: “342 Park A.”, “city”: “New York”},
“intereses”: [“tennis”, “basketball”, “running”]
}

Flujo básico de la box Webhook

En caso de que la petición realizada sea exitosa, y se obtenga una respuesta con código de status HTTP dentro del rango 200 – 299,  el flujo del bot continuará por la salida verde denominada “HTTP response: 200”.

El flujo del bot continuará por la salida roja “Default” en cualquiera de los siguientes casos:

1. Se obtenga un response con código HTTP fuera del rango mencionado
2. No se obtenga response alguno, por ejemplo porque el server al que apuntamos no responde
3. Por un error propio, no se pueda enviar la petición. Por ejemplo, la URL a la que apuntamos es inválida por no comenzar con http:// ni https://.

Ruteo según tipo de respuesta HTTP

Puedes definir un ruteo específico en función del código de status HTTP que obtengas en la respuesta. Por ejemplo, supongamos que necesitas realizar una acción en particular si el resultado de tu petición arroja un código HTTP 404 (not found). Para ello, deberías hacer clic en el botón “+ Agregar” de la sección “HTTP Response Routing” del sidebar de edición y escribir el valor 404. Luego hacer clic en Aplicar para aplicar los cambios.

Aparecerá una nueva salida en la box para el código de status HTTP 404, y lo que permitirá que el flujo tome un camino diferente al que seguiría si obtuviéramos cualquier otro código de error.

De la misma manera, podemos definir ruteos específicos para los distintos tipos de códigos HTTP exitosos. Si bien una respuesta satisfactoria se indica generalmente con el código HTTP 200, en realidad hay un rango de valores (200 – 299) que también indican una respuesta satisfactoria, pero agregan información adicional. Por defecto, cualquier respuesta con código dentro de ese rango tomará la salida verde, a menos que se haya definido un ruteo específico para el código devuelto.

En ocasiones podríamos necesitar realizar una acción específica si recibiéramos una respuesta satisfactoria con un código diferente a 200.

En el ejemplo siguiente, se ha definido un ruteo específico para el caso de obtener respuesta satisfactoria a nuestra petición, con el código 204 (No content).

Las respuestas HTTP se agrupan en cinco clases:

1. Respuestas informativas (100–199),
2. Respuestas satisfactorias (200–299),
3. Redirecciones (300–399),
4. Errores de los clientes (400–499),
5. y errores de los servidores (500–599).

Puesto que dentro de cada clase hay un sinnúmero de valores posibles, la box también te permite diseñar el flujo de tu bot según rangos de códigos HTTP. Para ello deberás ingresar el número mínimo y máximo del rango, separándolos con un guion medio. Ej.:

En caso de que la petición no se haya completado, y por lo tanto no se recibió la correspondiente respuesta, por ejemplo si la URL no existiera o fuera incorrecta (error nuestro), o el server al que apuntamos no está respondiendo (error del servidor), el flujo continuará por la salida roja “Default”.

Valores devueltos

El resultado de la petición se almacenará en el objeto {{webhook}}, el cual tendrá las propiedades status, que contendrá el código de estado HTTP de la respuesta, headers y data, que contendrán la información que vino con la respuesta. La propiedad data puede ser un string o un objeto con formato JSON.

Es decir que ante una petición exitosa, se generará un objeto webhook, similar al siguiente:

{
  status: 200,
  headers: {
    Content-Type: application/json,
    age: Fri, 15 May 2023 14:06:08 GMT
  },
  data: {
    client_id: 734634,
    client_name: ‘Fred’,
    likes: [‘jugar futbol’, ‘mirar videos’]
  }
}

Para acceder al objeto, por ejemplo para utilizarlo en el contenido de un mensaje, hacemos:

Hola {{webhook.data.client_name}}! Sabemos que te gusta {{webhook.data.likes[0]}} -> 
Hola Fred! Sabemos que te gusta jugar futbol

En caso de que la petición no se haya podido completar o no hayamos obtenido respuesta, por ejemplo porque la URL no existiera o fuera incorrecta, o porque el server al que apuntamos no está respondiendo, el objeto {{Webhook}} contendrá las propiedades error_message y error_code, las cuales nos darán información acerca del problema.