Webhook

Imagine que você administra uma loja de roupas online. Toda vez que cadastra um produto novo, há tarefas de bastidor que você precisa fazer pessoalmente. Coisas como traduzir a descrição do produto para outros idiomas ou avisar a equipe pelo mensageiro interno sobre o cadastro. Em vez de fazer essas tarefas à mão toda vez, você pode fazer com que, no momento em que o produto é cadastrado, um programa externo seja avisado automaticamente e cuide delas no seu lugar. Esse "mecanismo que, quando algo acontece, avisa automaticamente um lugar definido de antemão" é o Webhook.

Dá para comparar com a campainha instalada na porta da loja. Quando um cliente abre a porta e entra (quando um produto é cadastrado), a campainha toca por conta própria, e o funcionário lá dentro (o programa externo) percebe "chegou um cliente" e começa a agir na hora. Ninguém precisa ficar vigiando a porta o tempo todo. O Webhook, como essa campainha, envia uma requisição para o lugar definido no momento em que o evento definido acontece.

Nesta página, primeiro vamos ver o que é o Webhook e em que casos ele é usado, e depois criar um Webhook diretamente no Space da loja de roupas. Também tratamos do WriteBack, que preenche de volta no produto o resultado devolvido pelo programa externo.

O que o Webhook faz

O Webhook é formado por três coisas definidas de antemão.

• Quando enviar: você define em que evento a requisição será enviada. Por exemplo, é possível definir "quando um produto (Content) for cadastrado".
• Para onde enviar: você define o endereço do programa externo que vai receber a requisição. Basta anotar um endereço de internet (URL).
• Ligar ou desligar: você define se esse Webhook fica ligado agora (ACTIVE) ou desligado por um tempo (INACTIVE). Se ficar desligado, ele não envia requisição mesmo que o evento definido aconteça.

Quando o evento definido realmente acontece, o Webhook envia para o endereço anotado uma requisição avisando o ocorrido. A requisição leva informações como o que aconteceu e em qual produto aconteceu. O programa externo que recebe a requisição olha essas informações e faz a sua parte.

A que mudanças a requisição é enviada

O "evento" que dispara a requisição é uma mudança que ocorre em um recurso dentro do Space. Você pode escolher quando algo acontece a um Content como um produto, a um Media que é um arquivo enviado, ou a um Content Type que é o molde do formulário.

As mudanças que você pode escolher para cada recurso são as seguintes.

Por exemplo, "envie uma requisição toda vez que um produto for cadastrado" é escolher o Create do produto (Content).

Você também pode escolher várias mudanças juntas em um único Webhook. Se escolher tanto "quando um produto for cadastrado" quanto "quando um produto for modificado", a requisição é enviada se qualquer uma das duas acontecer.

Restringir com condições

Há casos em que você não quer enviar a requisição sempre que a mudança escolhida acontece. Por exemplo, talvez você queira receber apenas "quando um Content feito com o molde 'produto' for cadastrado, e não todos os Content". Nesses casos, você aplica um filtro para restringir os casos em que a requisição é enviada.

Cada filtro é formado por uma linha que diz "com base em quê, e como comparar". O que será usado como base para filtrar você escolhe entre quatro opções.

• Com qual molde o item foi feito: por exemplo, enviar a requisição apenas para o Content feito com o Content Type "produto". É a condição mais usada.
• Se é um item específico: enviar a requisição apenas para mudanças ocorridas naquele único item definido.
• Quem criou o item: enviar a requisição apenas para itens criados por uma pessoa específica.
• Quem alterou o item por último: enviar a requisição apenas para itens modificados por último por uma pessoa específica.

Você também escolhe a forma de comparar. É possível restringir para apenas quando for igual ao valor definido, apenas quando for diferente, apenas quando corresponder a um dos vários valores definidos, apenas quando não corresponder a nenhum deles, ou apenas quando corresponder ou não a um formato (padrão) definido.

Na configuração de gatilho do estúdio de conteúdo, você adiciona as condições uma linha por vez com Adicionar Filtro. Se você aplicar vários filtros, a requisição só é enviada quando todas as condições forem satisfeitas; se não aplicar nenhum, a requisição é enviada toda vez que a mudança escolhida acontecer.

Enviar no formato que o programa externo quer

Se você não definir nada à parte, a requisição leva por inteiro as informações do item em que a mudança ocorreu. Por exemplo, quando o produto da garrafa térmica é cadastrado, o conteúdo que vai na requisição tem mais ou menos este formato.

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

(Na prática vão mais informações; o acima é apenas uma parte resumida.) O programa externo escolhe daí o valor de que precisa e usa. Mas há programas com formato fixo, que "só aceitam receber neste formato". Nesse caso, na seção Payload do estúdio de conteúdo, você escolhe Personalizar o payload do Webhook e define você mesmo o formato a enviar.

Ao definir o formato a enviar, no lugar onde quer puxar valores dos dados acima, você usa um marcador de posição. O marcador tem o formato { /payload/… }. Aqui, payload se refere àquele item inteiro mostrado acima, e o caminho seguinte aponta exatamente o valor desejado.

• { /payload/sys/id } → o id dentro de sys dos dados acima (o número único do produto)
• { /payload/fields/productName/ko-KR } → o ko-KR de productName dentro de fields (o nome do produto em coreano). Depois de fields/, você acrescenta em sequência o ID do Field (para o nome do produto, productName) e o código do idioma (para coreano, ko-KR).

Por exemplo, se um programa de tradução pede "me dê o texto a traduzir e o número do produto neste formato", você define o payload assim.

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

Então, no momento em que o produto da garrafa térmica é cadastrado, os marcadores são trocados pelos valores reais e ele é entregue assim.

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

O mesmo marcador também pode ser colocado no endereço (URL) de envio ou no valor de um cabeçalho, e você também pode escolher junto a forma de envio (method) e o formato (JSON ou formato de formulário). Se não houver valor no caminho apontado, aquele lugar fica com valor vazio.

Valores que não podem ser vistos por outros, como uma chave de API externa, ao adicionar o cabeçalho, defina o tipo deles como Segredo. Assim esse valor é guardado oculto e não fica exposto ao usuário final.

Preencher de volta com a resposta recebida: WriteBack

Se a seção anterior trata de definir o formato da requisição que sai, o WriteBack trata da resposta que volta. Quando o Webhook chama o programa externo e recebe uma resposta normal (2xx), ele pode processar essa resposta para criar, alterar, publicar ou excluir um Content ou Media dentro do Space. O passo em que uma pessoa copia o resultado e cola à mão deixa de existir.

Vamos seguir o exemplo de tradução da loja de roupas até o fim. Antes, enviamos o nome do produto novo em coreano ao programa de tradução. Suponha que o programa de tradução responda assim.

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

Você configura um WriteBack que preenche esse texto traduzido no campo do nome do produto em inglês desse mesmo produto. Na seção WriteBack do estúdio de conteúdo, em Adicionar Operação você adiciona mais uma operação de Update (modificação) de Content e define assim.

• Alvo: se você não definir nada à parte, o alvo passa a ser aquele produto em que a mudança ocorreu (a garrafa térmica).
• Campo e idioma a preencher: como é o nome do produto em inglês, o campo é o nome do produto (productName) e o idioma é inglês (en-US).
• Valor a inserir: { /response/translated }, que aponta o texto traduzido da resposta.

Então o campo do nome do produto em inglês da garrafa térmica é preenchido com Stainless Tumbler 500ml.

Esse tipo de WriteBack é especialmente útil para conectar com um LLM externo. Por exemplo, você pode montar com um único Webhook um fluxo que envia a descrição do produto, salva como Media a imagem promocional gerada, ou cria um novo Content com o texto de apresentação gerado.

Ordem de execução

1. Quando a mudança ocorre, o Webhook envia ao programa externo uma requisição no formato definido.
2. Se a resposta for 2xx, as operações de WriteBack adicionadas são executadas de cima para baixo, em ordem.
3. Cada operação é independente das demais, então, mesmo que uma falhe, as restantes continuam sendo executadas.
4. Criações, modificações, exclusões e publicações geradas pelo WriteBack também são captadas como mudanças, podendo chamar em cadeia outro Webhook que assina essa mudança. Ciclos infinitos são verificados automaticamente e bloqueados quando você cria ou altera um Webhook.

O criador (createdBy) do recurso criado ou alterado pelo WriteBack passa a ser o usuário que provocou a mudança.

Expressões de valor

O valor a preencher é obtido com o mesmo marcador de posição ({ /… }) visto antes. Porém, no WriteBack há duas raízes que você pode apontar.

• Se você usar um único marcador sozinho ({ /response/url }), o valor é obtido na sua forma original (texto, número, agrupamento).
• Se você misturar com texto ("Criado: { /payload/sys/id }"), tudo se junta em um único texto.
• Quando a resposta não vem em JSON, mas como texto puro, use { /response } para receber a resposta inteira como texto (os caminhos internos não podem ser apontados).

Tratar Content ($content)

É a operação que cria ou altera um Content com a resposta. Os itens que você define são os seguintes.

Tratar Media ($media)

É a operação que traz para dentro como Media o arquivo recebido na resposta, ou que altera o estado de um Media.

O $media também pode ser usado como valor de campo de um Content. Depois de trazer para dentro como Media o arquivo recebido na resposta, você conecta esse Media diretamente ao campo, criando de uma só vez um "Content que contém imagem".

O Delete, Archive, Unarchive de um Media trata não só a informação na lista, mas também o arquivo real que está no armazenamento.

Como configurar e exemplos

Na seção WriteBack do estúdio de conteúdo, em Adicionar Operação você adiciona as operações uma a uma. Você pode alternar entre o modo Visual, que preenche os itens na tela, e o modo JSON, em que você escreve diretamente um agrupamento writeBacks como o de baixo. O resultado é o mesmo de qualquer forma.

Criar um produto novo anexando uma imagem gerada por um LLM externo. Traga para dentro como Media o endereço da imagem contido na resposta e crie um novo Content que tenha essa imagem.

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

Enriquecer o próprio produto em que a mudança ocorreu. Se você omitir target, o alvo é o Content em que a mudança ocorreu. Preencha o valor da resposta no campo desse produto.

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

Criar apenas como Draft para publicar após revisão. Se você desligar publish, ele não publica e fica como rascunho, para que uma pessoa confira e depois publique.

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

Trazer a imagem da resposta para dentro como Media independente. Se receber por endereço, deixe encoding como Url; se receber pelos dados do arquivo contidos na resposta, deixe como Base64.

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

Delete, Publish, Unpublish, Archive, Unarchive têm o mesmo formato. Basta escrever action e o target alvo a alterar, e só o estado desse alvo muda (se omitir o alvo, o item em que a mudança ocorreu). Por exemplo, para publicar um Content indicado pela resposta, escreva assim.

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

Se você adicionar várias operações, elas são executadas na ordem em que foram escritas. É o caso de colocá-las em sequência, como "preencher o resultado da tradução no produto e, em seguida, trazer para dentro como Media a imagem promocional".

Verificar o resultado da execução

Como cada operação de WriteBack ficou você verifica no registro de chamadas do Webhook. Para cada operação fica registrado o seguinte.

Nas operações bem-sucedidas, pelo ID do resultado você consegue rastrear qual recurso foi criado ou alterado. Se a resposta não for 2xx, o WriteBack nem chega a ser executado, e o registro de resultado também fica vazio.

Pontos a saber

• Apenas uma mudança envia a requisição. Se um único Webhook captar ao mesmo tempo "cadastro (Create)" e "publicação (Publish)", o programa externo pode ser chamado duas vezes. Em um Webhook que usa WriteBack, escolha apenas uma mudança.
• Apenas move valores, não calcula. Ele vai só até extrair o valor da resposta e inseri-lo; não faz processamentos como desvio condicional ou repetição.
• Não tenta de novo. Se ocorrer um problema durante o processamento, aquela operação pode simplesmente se perder.
• Não deixe criar à toa. É bom restringir a permissão de um Content Type que só é criado por WriteBack, para que o usuário comum não consiga criá-lo diretamente.

Criar o Webhook da loja de roupas

Agora vamos criar um Webhook no Space da loja de roupas. É um Webhook que "quando um produto novo é cadastrado, avisa o ocorrido a um programa externo de tradução preparado de antemão". Vamos supor que o endereço do programa externo que vai receber a requisição é https://example.com/translate.

1. Nas configurações do Space da loja de roupas, abra a tela do Webhook.
2. Pressione o botão Criar no canto superior direito.
3. No campo de nome, digite Aviso de tradução de produto novo. Esse nome serve para você reconhecer depois de qual Webhook se trata.
4. Defina a mudança que vai enviar a requisição. Para enviar apenas em uma mudança específica, escolha Selecionar eventos acionadores específicos e indique a mudança desejada (aqui, o Create do produto (Content)); para enviar em todas as mudanças, escolha Acionar para todos os eventos.
5. No campo URL digite o endereço do programa externo que vai receber a requisição, https://example.com/translate.
6. Se você deixar Ativo ligado, ele envia requisições assim que for criado (ACTIVE). Para apenas testar por um tempo, deixe desligado (INACTIVE).
7. Pressione o botão Criar para criar o Webhook.

Quando Aviso de tradução de produto novo aparecer na lista no estado ACTIVE, o Webhook foi criado.

Depois de criar, experimente cadastrar de fato um produto novo na loja de roupas. No momento do cadastro, o Webhook envia uma requisição para o endereço anotado. Se a requisição foi enviada corretamente e como o programa externo respondeu você verifica no registro de chamadas do Webhook.

Ligar, desligar e modificar

Você pode ligar e desligar o Webhook a qualquer momento, mesmo depois de criado. Quando quiser parar as requisições por um tempo, não exclua: deixe desligado como INACTIVE. Enquanto estiver desligado, mesmo que você cadastre um produto novo a requisição não é enviada. Quando você ligar de novo como ACTIVE, ele volta a enviar requisições a partir daí.

Ao reabrir o Webhook criado, você pode desligar ou voltar a ligar Ativo. Conteúdos como o nome, o endereço de envio da requisição e a mudança a chamar também podem ser modificados depois, e um Webhook que você não usa mais basta excluir.

O que fazer em seguida

• Modelagem de Content: trata de como criar o molde de formulário de um Content como o "produto", que é o alvo cujas requisições o Webhook dispara.
• Criar Content: você pode cadastrar um produto real e verificar se o Webhook funciona.
• Referência da API: trata dos formatos de requisição/resposta e da especificação de campos usados quando você cria e gerencia o Webhook diretamente em um programa.