Webhook | Weegloo Docs

Imagine que gestiona la tienda en línea de una tienda de ropa. Cada vez que da de alta un nuevo producto hay tareas que debe atender personalmente. Por ejemplo, traducir la descripción del producto a otros idiomas o avisar del alta en el mensajero interno de la empresa. En lugar de hacer estas tareas a mano cada vez, puede avisar automáticamente a un programa externo en el instante en que se da de alta el producto para que las realice en su lugar. Ese "mecanismo que, cuando ocurre algo, avisa automáticamente al lugar fijado de antemano" es el Webhook.

Se puede comparar con el timbre colocado en la puerta de la tienda. Cuando un cliente abre la puerta y entra (cuando se da de alta un producto), el timbre suena por sí solo y el empleado que está dentro (el programa externo) empieza a moverse de inmediato pensando "ha llegado un cliente". Nadie tiene que vigilar la puerta de forma continua. El Webhook, igual que ese timbre, inicia automáticamente la acción fijada en el instante en que ocurre el suceso fijado.

En esta página primero veremos qué es el Webhook y en qué casos se usa, y después crearemos un Webhook directamente en el Space de la tienda de ropa.

Lo que hace el Webhook

El Webhook se compone de tres cosas que se fijan de antemano.

Cuándo: define ante qué suceso debe reaccionar. Por ejemplo, puede fijarlo como "cuando se da de alta un nuevo producto (Content)".
Qué hacer: elige una de dos cosas. O bien envía una petición a la dirección de internet (URL) de un programa externo, o bien ejecuta un Script creado dentro del Space.
Activar o desactivar: define si este Webhook se mantiene activado ahora (Active) o desactivado por un tiempo (Inactive). Mientras está desactivado, no hace nada aunque ocurra el suceso fijado.

Cuando el suceso fijado ocurre realmente, el Webhook realiza la acción fijada. Si envía a una dirección externa, la petición lleva información como qué ha ocurrido y en qué producto ha ocurrido. El programa externo que recibe la petición consulta esa información y hace su trabajo.

Ante qué cambios se envía la petición

El "suceso" que dispara la petición es un cambio que ocurre en un recurso dentro del Space. Puede elegir cuándo ocurre algo en un Content como un producto, en un Media (un archivo subido) o en un Content Type (la plantilla de formato).

Los cambios que puede elegir para cada recurso son los siguientes.

Cambio	Cuándo ocurre	Ejemplo de la tienda de ropa
Create	Cuando se crea de nuevo	Se da de alta un nuevo producto
Save	Cuando se modifica el contenido y se guarda	Se modifica y guarda la descripción de un producto
Delete	Cuando se elimina	Se borra un producto descatalogado
Publish	Cuando se publica y se hace público al exterior	Se publica un producto en el sitio
Unpublish	Cuando se cancela la publicación	Se retira del sitio un producto agotado
Archive	Cuando se archiva	Se archiva un producto de una temporada pasada
Unarchive	Cuando se desarchiva	Se recupera un producto archivado

Por ejemplo, "envía una petición cada vez que se da de alta un nuevo producto" consiste en elegir el Create del producto (Content).

También puede elegir varios cambios a la vez en un mismo Webhook. Si elige tanto "cuando se da de alta un producto" como "cuando se modifica un producto", la petición se envía si ocurre cualquiera de los dos.

Acotar mediante condiciones

A veces no quiere enviar la petición siempre que ocurre el cambio elegido. Por ejemplo, puede querer recibirla "solo cuando se da de alta un Content creado con el formato 'producto', no con cualquier Content". En ese caso, aplica un filtro para acotar los casos en que se envía la petición.

Cada filtro se compone de una línea que indica "según qué criterio y cómo comparar". El criterio por el que filtrar se elige entre cuatro opciones.

Con qué formato se ha creado el elemento: por ejemplo, envía la petición solo a los Content creados con el Content Type "producto". Es la condición que más se usa.
Si es un elemento concreto: envía la petición solo a los cambios ocurridos en ese único elemento fijado.
Quién ha creado el elemento: envía la petición solo a los elementos creados por una persona concreta.
Quién ha modificado por última vez el elemento: envía la petición solo a los elementos modificados por última vez por una persona concreta.

También se elige la forma de comparar. Puede acotar a cuando coincide con el valor fijado, a cuando es distinto, a cuando corresponde a uno de varios valores fijados, a cuando no corresponde a ninguno de ellos, o a cuando se ajusta o no a un formato (patrón) fijado.

En la configuración del disparador del estudio de contenidos, añada las condiciones de una en una con Agregar Filtro. Si aplica varios filtros, la petición se envía solo cuando se cumplen todas esas condiciones; si no aplica ninguno, la petición se envía cada vez que ocurre el cambio elegido.

Enviar con el formato que el programa externo quiere

Si no fija nada en concreto, la petición lleva en bloque la información del elemento en el que ha ocurrido el cambio. Por ejemplo, cuando se da de alta el producto del termo, el contenido que va en la petición tiene aproximadamente esta forma.

{
  "sys": { "id": "3trmXRM3RqbgSnifyg7OGhwhlqvAvq", "type": "Content" },
  "fields": {
    "productName": { "ko-KR": "스테인리스 텀블러 500ml" }
  }
}

(En realidad lleva más información; lo anterior es solo una parte resumida.) Al programa externo le basta con elegir de aquí los valores que necesita. Pero hay programas que tienen un formato fijado y que "solo aceptan recibir los datos con esta forma". En ese caso, en la sección Carga útil del estudio de contenidos elija Personalizar la carga útil del Webhook y escriba usted mismo la forma que quiere enviar.

Zona de cabecera y carga útil de la pantalla de creación de Webhook. Con la opción de incluir el cuerpo de la petición activada y Personalizar la carga útil del Webhook seleccionado, se escribe en el editor JSON de abajo la forma que se va a enviar

Al escribir la forma que va a enviar, en los lugares donde quiere insertar un valor tomado de los datos anteriores se usa un marcador de posición. El marcador de posición tiene la forma { /payload/… }. Aquí payload se refiere a ese elemento completo mostrado arriba, y la ruta que sigue señala con precisión el valor deseado.

{ /payload/sys/id } → el id dentro de sys de los datos anteriores (el número único del producto)
{ /payload/fields/productName/ko-KR } → el ko-KR de productName dentro de fields (el nombre del producto en coreano). Tras fields/ se añaden por orden el ID del Field (en el caso del nombre del producto, productName) y el código de idioma (en el caso del coreano, ko-KR).

Por ejemplo, si un programa de traducción pide "dame el texto a traducir y el número del producto con esta forma", se escribe el payload así.

{
  "id": "{ /payload/sys/id }",
  "text": "{ /payload/fields/productName/ko-KR }"
}

Entonces, en el instante en que se da de alta el producto del termo, los marcadores de posición se sustituyen por los valores reales y se transmite así.

{
  "id": "3trmXRM3RqbgSnifyg7OGhwhlqvAvq",
  "text": "스테인리스 텀블러 500ml"
}

Los mismos marcadores de posición se pueden poner también en la dirección de envío (URL) o en los valores de cabecera, y además puede elegir la forma de envío (method) y el formato (JSON o formato de formulario). Si en la ruta señalada no hay valor, ese lugar queda con un valor vacío.

Los valores que no deben quedar a la vista de otros, como una clave de API externa, al añadir la cabecera, defina su tipo como Secreto. Así ese valor se guarda oculto y no queda expuesto al usuario final.

El desplegable de tipo abierto al añadir una cabecera. Se elige entre Secreto, Autenticación básica HTTP y Personalizado

Ejecutar un Script en lugar de una URL

Hasta ahora el Webhook enviaba una petición a una dirección externa (URL). En lugar de eso, el Webhook también puede ejecutar un Script creado dentro del Space. El Script es un mecanismo que, sin salir al exterior, realiza dentro del Space un trabajo fijado de antemano (crear recursos, modificarlos, etc.). Use esta vía cuando quiera terminar las tareas pendientes dentro del Space sin pasar por un programa externo.

Un mismo Webhook hace exactamente una de las dos cosas: enviar a una dirección externa o ejecutar un Script. Se define en Destino de la solicitud de la pantalla de creación. Si elige Introducir URL, envía la petición a la dirección como antes; en cambio, si elige un Script de la lista, ejecuta ese Script.

Al elegir un Script aparece además Run as, que decide con qué identidad se ejecuta ese Script. Elija una de las dos opciones.

Creador del Webhook (predeterminado): el "creado por" de los recursos que se crean o se modifican durante la ejecución queda registrado como la persona que creó el Webhook.
Usuario que lo desencadena: queda registrado como el usuario que provocó ese cambio.

Este ajuste solo decide la marca de "quién lo hizo" que queda en los recursos; no amplía ni reduce lo que el Script puede hacer. El alcance de lo que un Script puede hacer ya queda fijado cuando se crea ese Script.

El orden para elegirlo en la práctica es el siguiente.

En la pantalla de creación, pulse Destino de la solicitud.
Elija en la lista el Script que se ejecutará. Se trata de elegir un Script en lugar de Introducir URL.
En Run as, elija la identidad. El valor predeterminado es Creador del Webhook.

Pantalla de creación de Webhook con el Script «Rellenar la descripción del producto» elegido como destino de la solicitud. Junto a la URL de llamada rellenada, Run as aparece con las dos opciones Creador del Webhook y Usuario que lo desencadena

Qué es un Script y cómo se crea se trata en Script.

Crear el Webhook de la tienda de ropa

Ahora crearemos un Webhook en el Space de la tienda de ropa. Es un Webhook que "cuando se da de alta un nuevo producto, avisa de ese hecho al programa de traducción externo preparado de antemano". Supongamos que la dirección del programa externo que recibirá la petición es https://example.com/translate.

En la configuración del Space de la tienda de ropa, abra la pantalla de Webhook.
Pulse el botón Crear de la parte superior derecha.
Escriba Aviso de traducción de nuevo producto en el campo del nombre. Este nombre sirve para reconocer después de qué Webhook se trata.
Defina el cambio ante el que se enviará la petición. Para enviarla solo ante un cambio concreto, elija Seleccionar eventos activadores específicos y luego indique el cambio deseado (aquí, el Create del producto (Content)); para enviarla ante todos los cambios, elija Activar para todos los eventos.
Escriba en el campo URL la dirección del programa externo que recibirá la petición, https://example.com/translate.
Si mantiene activado Activo, envía la petición en cuanto lo crea (Active). Si solo quiere hacer pruebas por un momento, déjelo desactivado (Inactive).
Pulse el botón Crear para crear el Webhook.

Pantalla de creación de un nuevo Webhook. El nombre, la activación, la selección del disparador y la URL rellenados

Cuando Aviso de traducción de nuevo producto aparezca en la lista con estado Active, es que el Webhook se ha creado.

Pantalla en la que "Aviso de traducción de nuevo producto" se ve con estado Active en la lista de Webhook

Después de crearlo, dé de alta realmente un nuevo producto en la tienda de ropa. En el instante del alta, el Webhook envía la petición a la dirección anotada. Si la petición se ha enviado bien y cómo ha respondido el programa externo puede comprobarlo en el registro de llamadas del Webhook.

Activar, desactivar y modificar

El Webhook se puede activar y desactivar en cualquier momento incluso después de crearlo. Cuando quiera detener las peticiones por un tiempo, no lo elimine; déjelo desactivado en Inactive. Mientras esté desactivado, aunque dé de alta un nuevo producto la petición no se envía. Si lo vuelve a activar a Active, a partir de ese momento vuelve a enviar peticiones.

Si vuelve a abrir el Webhook creado, puede desactivar o volver a activar Activo. También puede modificar después el nombre, la dirección de envío de la petición o el cambio que la dispara, y los Webhook que ya no use puede eliminarlos.

Qué hacer a continuación

Modelado de Content: trata cómo crear la plantilla de formato de los Content como el "producto", que es el objetivo cuyas peticiones dispara el Webhook.
Crear Content: puede dar de alta un producto real y comprobar si el Webhook funciona.
Script: trata cómo crear el trabajo que se ejecuta dentro del Space y que el Webhook puede ejecutar en lugar de una URL.
Referencia de API: trata los formatos de petición y respuesta y la especificación de campos que se usan al crear y gestionar el Webhook directamente desde un programa.