Webhook

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, envía una petición al lugar fijado 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. También trataremos el WriteBack, que vuelve a rellenar en el producto el resultado que devuelve el programa externo.

Lo que hace el Webhook

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

• Cuándo enviar: define ante qué suceso se envía la petición. Por ejemplo, puede fijarlo como "cuando se da de alta un nuevo producto (Content)".
• A dónde enviar: define la dirección del programa externo que recibirá la petición. Anota una dirección de internet (URL).
• Activar o desactivar: define si este Webhook se mantiene activado ahora (ACTIVE) o desactivado por un tiempo (INACTIVE). Si lo desactiva, no envía la petición aunque ocurra el suceso fijado.

Cuando el suceso fijado ocurre realmente, el Webhook envía a la dirección anotada una petición que avisa de ese hecho. 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.

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.

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.

Rellenar de vuelta con la respuesta recibida: WriteBack

Si el apartado anterior define la forma de la petición que se envía, el WriteBack trata la respuesta que regresa. Cuando el Webhook llama al programa externo y recibe una respuesta correcta (2xx), puede procesar esa respuesta para crear, modificar, publicar o eliminar un Content o un Media dentro del Space. Desaparece el proceso de que una persona copie y pegue el resultado.

Seguiremos hasta el final el ejemplo de la traducción de la tienda de ropa. Antes enviamos al programa de traducción el nombre en coreano del nuevo producto. Supongamos que el programa de traducción responde así.

{ "translated": "Stainless Tumbler 500ml" }

Configure un WriteBack que rellene esta traducción en el campo del nombre del producto en inglés del mismo producto. En la sección WriteBack del estudio de contenidos, con + Añadir Operación añada una acción Update (modificar) de Content y configúrela así.

• Destino: si no fija nada en concreto, el destino será ese producto en el que ocurrió el cambio (el termo).
• Campo e idioma a rellenar: como es el nombre del producto en inglés, el campo es el nombre del producto (productName) y el idioma es el inglés (en-US).
• Valor a insertar: { /response/translated }, que señala la traducción de la respuesta.

Entonces el campo del nombre del producto en inglés del producto del termo se rellena con Stainless Tumbler 500ml.

Este tipo de WriteBack resulta especialmente útil para conectar con un LLM externo. Por ejemplo, puede configurar con un solo Webhook un flujo que guarde como Media una imagen promocional generada a partir de la descripción del producto, o que cree un nuevo Content con el texto de presentación generado.

Orden de ejecución

1. Cuando ocurre el cambio, el Webhook envía la petición al programa externo con la forma fijada.
2. Si la respuesta es 2xx, ejecuta las acciones (operaciones) de WriteBack añadidas por orden, de arriba a abajo.
3. Cada acción es independiente de las demás, así que aunque una falle, el resto sigue ejecutándose.
4. Las creaciones, modificaciones, eliminaciones y publicaciones que surgen del WriteBack también se detectan de nuevo como cambios, y pueden llamar en cadena a otros Webhook que estén suscritos a ese cambio. Los ciclos sin fin se comprueban automáticamente al crear o modificar un Webhook y se bloquean.

El creador (createdBy) del recurso creado o modificado por el WriteBack es el usuario que provocó ese cambio.

Expresiones de valor

El valor a rellenar se toma con el mismo marcador de posición ({ /… }) que se vio antes. Sin embargo, en el WriteBack hay dos raíces que se pueden señalar.

• Si usa un único marcador de posición solo ({ /response/url }), toma tal cual la forma original del valor (texto, número, conjunto).
• Si lo mezcla con texto ("Creado: { /payload/sys/id }"), se concatena en un solo texto.
• Cuando la respuesta no es JSON sino texto plano, use { /response } para recibir toda la respuesta como texto (no se pueden señalar las rutas internas que contiene).

Manejar Content ($content)

Es la acción de crear o modificar un Content con la respuesta. Los elementos que se fijan son los siguientes.

Manejar Media ($media)

Es la acción de incorporar como Media el archivo recibido en la respuesta o de cambiar el estado de un Media.

$media también se puede usar como valor de campo de un Content. Tras incorporar como Media el archivo recibido en la respuesta, puede enlazar ese Media directamente al campo y crear de una sola vez un "Content que contiene una imagen".

El Delete, Archive, Unarchive de un Media procesa no solo la información de la lista, sino también el archivo real que está en el almacenamiento.

Cómo configurarlo y ejemplos

En la sección WriteBack del estudio de contenidos, con + Añadir Operación añada las acciones de una en una. Puede alternar entre el método Visual, en el que rellena los elementos en la pantalla, y el método JSON, en el que escribe directamente un conjunto writeBacks como el de abajo. El resultado es el mismo por cualquiera de las dos vías.

Crear un nuevo producto adjuntando una imagen generada por un LLM externo. Incorpora como Media la dirección de imagen incluida en la respuesta y crea un nuevo Content que tiene esa imagen.

{
  "writeBacks": [
    {
      "$content": {
        "action": "Create",
        "contentType": { "sys": { "id": "<Producto Content Type sys.id>" } },
        "fields": {
          "productName": "{ /payload/fields/productName/ko-KR }",
          "photo": { "$media": { "source": "{ /response/data/0/url }", "encoding": "Url" } }
        }
      }
    }
  ]
}

Enriquecer ese producto en el que ocurrió el cambio. Si omite target, el destino es el Content en el que ocurrió el cambio. Rellena el valor de la respuesta en el campo de ese producto.

{
  "writeBacks": [
    {
      "$content": {
        "action": "Update",
        "locale": "en-US",
        "fields": { "productName": "{ /response/translated }" }
      }
    }
  ]
}

Crearlo solo como Draft para publicarlo tras revisión. Si desactiva publish, no se publica y queda como borrador, de modo que se pueda publicar después de que una persona lo haya revisado.

{
  "writeBacks": [
    {
      "$content": {
        "action": "Create",
        "contentType": { "sys": { "id": "<Content Type sys.id>" } },
        "fields": { "text": "{ /response/choices/0/message/content }" },
        "publish": false
      }
    }
  ]
}

Incorporar la imagen de la respuesta como un Media independiente. Si la recibe por dirección, ponga encoding en Url; si la recibe como datos de archivo incluidos en la respuesta, en Base64.

{
  "writeBacks": [
    { "$media": { "action": "Create", "source": "{ /response/data/0/url }", "encoding": "Url" } }
  ]
}

Delete, Publish, Unpublish, Archive, Unarchive tienen la misma forma. Si solo escribe el action y el target de destino a cambiar, solo cambia el estado de ese destino (si omite el destino, ese elemento en el que ocurrió el cambio). Por ejemplo, para publicar el Content indicado por la respuesta, se escribe así.

{
  "writeBacks": [
    { "$content": { "action": "Publish", "target": "{ /response/contentId }" } }
  ]
}

Si añade varias acciones, se ejecutan en el orden en que las escribió. Es como ponerlas seguidas, del tipo "rellenar el resultado de la traducción en el producto y, a continuación, incorporar la imagen promocional como Media".

Comprobar el resultado de la ejecución

Cómo ha quedado cada acción de WriteBack se comprueba en el registro de llamadas del Webhook. De cada acción queda lo siguiente.

En las acciones correctas puede seguir, mediante el ID del resultado, qué recurso se creó o se modificó. Si la respuesta no es 2xx, el WriteBack no se ejecuta en absoluto, así que el registro de resultados también queda vacío.

Cosas que conviene saber

• El cambio que envía la petición debe ser uno solo. Si un mismo Webhook captura a la vez "alta (Create)" y "publicación (Publish)", el programa externo puede ser llamado dos veces. En un Webhook que usa WriteBack, elija un solo cambio.
• Solo traslada valores; no puede calcular. Solo llega a extraer valores de la respuesta e insertarlos; no realiza procesos como ramificaciones condicionales o repeticiones.
• No reintenta. Si surge un problema durante el procesamiento, esa acción puede perderse sin más.
• Que no se cree a la ligera. Conviene restringir los permisos para que los usuarios normales no puedan crear directamente un Content Type que solo se crea mediante WriteBack.

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.

1. En la configuración del Space de la tienda de ropa, abra la pantalla de Webhook.
2. Pulse el botón Crear de la parte superior derecha.
3. 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.
4. 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.
5. Escriba en el campo URL la dirección del programa externo que recibirá la petición, https://example.com/translate.
6. 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).
7. Pulse el botón Crear para crear el Webhook.

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

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.
• 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.