Webhook

O Webhook é uma configuração que envia uma requisição HTTP para uma URL externa previamente definida quando algo acontece no Space (por exemplo, criação ou publicação de Content). É usado para integração com sistemas externos ou automação. Por exemplo, você pode configurá-lo para chamar um servidor de notificações interno sempre que um Content de produto for publicado, ou para chamar uma API externa.

O Webhook não se limita a enviar a requisição: ele também pode receber a resposta e gravá-la de volta em um Content ou Media por meio do WriteBack. É assim que se constrói um fluxo de trabalho assíncrono que absorve o resultado de uma API externa como dados dentro do Space. O Webhook é um recurso subordinado ao Space na CMA, e seu caminho tem como base /spaces/{spaceId}/webhooks.

Estrutura do recurso

A seguir está a resposta da consulta individual do Webhook "Notificação de alteração de produto". Junto com sys (atributos de sistema), ele tem campos de configuração como destino de envio, eventos assinados e condições de disparo.

{
  "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": "Notificação de alteração de produto",
  "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
}

Principais chaves:

• sys.id: identificador único do Webhook. Entra no {webhookId} dos caminhos de consulta individual, modificação e exclusão.
• url: URL de destino externa a ser chamada quando o evento ocorrer.
• topics: array que define quais eventos serão assinados. O formato é explicado abaixo em topics.
• filters: condições que efetivamente disparam, dentre os eventos assinados. É explicado abaixo em filters.
• transformation: configuração que altera o formato da requisição de saída (método, corpo etc.). É explicado abaixo em transformation.
• writeBacks: array de operações que recebem a resposta externa e gravam de volta em Content ou Media. Não está presente no exemplo acima. É explicado abaixo em writeBacks.

Atributos de sistema (sys)

Todo Webhook armazena os atributos de sistema comuns no objeto sys. space, createdBy e updatedBy entram no formato Refer ({ "sys": { "id", "type": "Refer", "targetType" } }).

O Webhook é um recurso de configuração, portanto não tem o conceito de publicação. Diferentemente de Content ou Content Type, ele não possui atributos de estado de publicação como publish, archive ou status, apenas o version para rastreamento de alterações. Ligar e desligar não é controlado por publicação, mas pelo campo de corpo activate.

Atributos do corpo

O corpo do Webhook (os valores de configuração enviados na criação e modificação e retornados na resposta) é composto pelos seguintes campos.

Cada item de headers é composto por key (obrigatório), value (obrigatório) e secret (opcional, boolean). Cabeçalhos com secret igual a true têm o valor ocultado na resposta. Coloque valores que não devem ser expostos, como chaves de API, em cabeçalhos com secret: true.

topics

Cada item de topics tem o formato {recurso}.{ação}. Por exemplo: Content.Create, Content.Publish, Media.Create.

A ação é uma das seguintes ou *, que significa todas as ações do recurso (por exemplo, Content.*).

filters

filters é um array que restringe, dentre os topics assinados, as condições que efetivamente disparam o Webhook. Cada filtro tem o seguinte formato.

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

• doc: caminho do campo a comparar. É um dentre sys.id, sys.contentType.sys.id, sys.createdBy.sys.id e sys.updatedBy.sys.id.
• op: operador de comparação. É um dentre EQ, NE, IN, NOT_IN, REGEX e NOT_REGEX.
• value: valor de comparação. Para EQ, NE, REGEX e NOT_REGEX informe uma string; para IN e NOT_IN informe um array de strings.

Quando há vários filtros, todos precisam ser satisfeitos para disparar (AND). Se filters estiver vazio, todos os eventos dos topics assinados disparam.

transformation

transformation altera o formato da requisição HTTP de saída. Se não for especificado, todo o payload do recurso sai como está, com o POST padrão.

writeBacks

writeBacks é um array ordenado de operações que pegam a resposta externa recebida pelo Webhook e gravam de volta em Content ou Media. Elas são executadas em ordem somente quando a API externa responde com 2xx. Cada item tem um único $content (WriteBackContent) ou $media (WriteBackMedia).

Chaves de WriteBackContent ($content):

Chaves de WriteBackMedia ($media):

A seguir está um exemplo de writeBacks que extrai valores do JSON de resposta externa e cria um Content.

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

{ /response/... } é um template de JSON Pointer que extrai valores do JSON de resposta recebido pelo Webhook. As chaves de fields (productName, price) são o apiName dos campos do Content alvo. O exemplo acima preenche o title da resposta no productName do Content e o price em price, cria o Content e depois o publica.

API

A URL base de todos os endpoints abaixo é https://cma.weegloo.com/v1, e é necessário um token Bearer no cabeçalho Authorization que autentique na CMA. A modificação (PUT) e a modificação parcial (PATCH) devem enviar também o cabeçalho X-Weegloo-Version (o sys.version do recurso atual) para o controle de concorrência otimista.

Documentos relacionados

• Content: dados de corpo que disparam o Webhook ou que ele grava por WriteBack.
• Media: recurso de arquivo que pode ser criado por WriteBack.
• SpaceRole: para restringir com :self o acesso ao Content de trabalho do Webhook.