Webhook

Un Webhook es una configuración que envía una petición HTTP a una URL externa predefinida cuando ocurre un evento en un Space (por ejemplo, la creación o publicación de un Content). Se usa para integraciones con sistemas externos o para automatización. Por ejemplo, puede configurarse para llamar a un servidor de notificaciones interno cada vez que se publica un Content de producto, o para invocar una API externa.

Un Webhook no se limita a enviar la petición: también puede configurar un WriteBack que reciba la respuesta y la vuelva a escribir en un Content o un Media. Así se construye un flujo de trabajo asíncrono que absorbe el resultado de una API externa como datos dentro del Space. El Webhook es un recurso hijo de Space en CMA, y su ruta se basa en /spaces/{spaceId}/webhooks.

Estructura del recurso

A continuación se muestra la respuesta de consulta individual del Webhook "Notificación de cambio de producto". Junto con sys (propiedades del sistema), tiene campos de configuración como el destino del envío, los eventos suscritos y las condiciones de activación.

{
  "sys": {
    "id": "3trmXRM3RqbgSnifyg7PWhk01Examp",
    "type": "Webhook",
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-06-18T11:30:00.000Z",
    "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-06-18T11:30:00.000Z",
    "version": 1
  },
  "name": "Notificación de cambio de producto",
  "filters": [
    { "doc": "sys.contentType.sys.id", "op": "EQ", "value": "3trmXRLdJF4GBlAjtcuoZ7Pnxj8dlA" }
  ],
  "headers": [
    { "key": "X-Source", "value": "weegloo", "secret": false }
  ],
  "httpBasicUsername": "dailywear",
  "topics": ["Content.Create", "Content.Publish"],
  "transformation": { "method": "POST", "contentType": "application/json", "includeBody": true },
  "url": "https://api.dailywear.example/webhooks/products",
  "activate": true
}

Claves principales:

• sys.id: identificador único del Webhook. Se inserta en {webhookId} de las rutas de consulta individual, modificación y eliminación.
• url: URL de destino externa a la que se llama cuando ocurre el evento.
• topics: array que define qué eventos se suscriben. El formato se explica más abajo en topics.
• filters: condiciones que realmente activan el Webhook entre los eventos suscritos. Se explica más abajo en filters.
• transformation: configuración que modifica la forma de la petición saliente (método, cuerpo, etc.). Se explica más abajo en transformation.
• writeBacks: array de operaciones que reciben la respuesta externa y la vuelven a escribir en un Content o un Media. No está presente en el ejemplo anterior. Se explica más abajo en writeBacks.

Propiedades del sistema (sys)

Todo Webhook incluye sus propiedades de sistema comunes en el objeto sys. space, createdBy y updatedBy se incluyen con la forma Refer ({ "sys": { "id", "type": "Refer", "targetType" } }).

Como el Webhook es un recurso de configuración, no tiene el concepto de publicación. A diferencia de Content o Content Type, no posee propiedades de estado de publicación como publish, archive o status, sino solo version para el seguimiento de cambios. Su activación y desactivación no se controlan mediante publicación, sino con el campo del cuerpo activate.

Propiedades del cuerpo

El cuerpo del Webhook (los valores de configuración que se envían al crear o modificar y que se devuelven en la respuesta) se compone de los siguientes campos.

Cada elemento de headers se compone de key (obligatorio), value (obligatorio) y secret (opcional, boolean). En las cabeceras cuyo secret es true, el valor se oculta en la respuesta. Los valores que no deben quedar expuestos, como las claves de API, se colocan en cabeceras con secret: true.

topics

Cada elemento de topics tiene el formato {recurso}.{acción}. Por ejemplo: Content.Create, Content.Publish, Media.Create.

La acción es una de las siguientes, o *, que significa todas las acciones del recurso (por ejemplo, Content.*).

filters

filters es un array que acota qué condiciones activan realmente el Webhook entre los topics suscritos. Cada filtro tiene la siguiente forma.

{ "doc": "sys.contentType.sys.id", "op": "EQ", "value": "3trmXRLdJF4GBlAjtcuoZ7Pnxj8dlA" }

• doc: ruta del campo a comparar. Es una de sys.id, sys.contentType.sys.id, sys.createdBy.sys.id o sys.updatedBy.sys.id.
• op: operador de comparación. Es uno de EQ, NE, IN, NOT_IN, REGEX o NOT_REGEX.
• value: valor de comparación. Para EQ, NE, REGEX y NOT_REGEX se da una cadena; para IN y NOT_IN, un array de cadenas.

Si se definen varios filtros, todos deben cumplirse para que se active (AND). Si se deja filters vacío, se activan todos los eventos de los topics suscritos.

transformation

transformation modifica la forma de la petición HTTP saliente. Si no se especifica, todo el payload del recurso sale tal cual con el POST predeterminado.

writeBacks

writeBacks es un array ordenado de operaciones que toman la respuesta externa recibida por el Webhook y la vuelven a escribir en un Content o un Media. Solo se ejecutan en orden cuando la API externa responde con un 2xx. Cada elemento contiene un único $content (WriteBackContent) o $media (WriteBackMedia).

Claves de WriteBackContent ($content):

Claves de WriteBackMedia ($media):

A continuación se muestra un ejemplo de writeBacks que extrae valores del JSON de respuesta externa y crea un Content.

"writeBacks": [
  {
    "$content": {
      "action": "Create",
      "contentType": { "sys": { "id": "3trmXRLdJF4GBlAjtcuoZ7Pnxj8dlA" } },
      "locale": "ko-KR",
      "fields": {
        "productName": "{ /response/title }",
        "price": "{ /response/price }"
      },
      "publish": true,
      "unpublish": true
    }
  }
]

{ /response/... } es una plantilla de JSON Pointer que extrae valores del JSON de respuesta recibido por el Webhook. Las claves de fields (productName, price) son los apiName de los campos del Content de destino. El ejemplo anterior rellena el title de la respuesta en productName del Content y el price en price, crea el Content y luego lo publica.

API

La URL base de todos los endpoints siguientes es https://cma.weegloo.com/v1, y se requiere un token Bearer que autentique en CMA en la cabecera Authorization. La modificación (PUT) y la modificación parcial (PATCH) deben enviar además la cabecera X-Weegloo-Version (el sys.version del recurso actual) para el control de concurrencia optimista.

Documentos relacionados

• Content: los datos del cuerpo que activan el Webhook o que se escriben mediante WriteBack.
• Media: el recurso de archivo que se puede crear mediante WriteBack.
• SpaceRole: cuando se restringe con :self el acceso al Content de las operaciones del Webhook.