Webhook | Weegloo Docs

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, inicia automaticamente uma ação definida no momento em que o evento definido acontece.

Nesta página, você primeiro verá o que é o Webhook e em que casos ele é usado, e depois criará um Webhook diretamente no Space da loja de roupas.

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".
O que fazer: você define uma de duas coisas. Ou envia uma requisição para o endereço de internet (URL) de um programa externo, ou executa um Script criado dentro do Space.
Ligar ou desligar: você define se esse Webhook fica ligado agora (Active) ou desligado por um tempo (Inactive). Se ficar desligado, ele não faz nenhuma ação mesmo que o evento definido aconteça.

Quando o evento definido realmente acontece, o Webhook executa a ação definida. No caso de envio para um endereço externo, 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.

Mudança	Quando acontece	Exemplo da loja de roupas
Create	Quando é criado	Cadastrar um produto novo
Save	Quando o conteúdo é alterado e salvo	Corrigir e salvar a descrição do produto
Delete	Quando é excluído	Remover um produto descontinuado
Publish	Quando é publicado e exposto externamente	Tornar o produto público no site
Unpublish	Quando a publicação é cancelada	Tirar do site um produto esgotado
Archive	Quando é arquivado	Arquivar um produto da temporada passada
Unarchive	Quando o arquivamento é desfeito	Restaurar um produto arquivado

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 "Copo térmico de aço inox 500ml" é 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.

Área de cabeçalho e payload da tela de criação de Webhook. Com a inclusão do corpo da requisição ativada e Personalizar o payload do Webhook selecionado, escreve-se no editor JSON abaixo 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 do copo térmico é 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.

Para valores que não devem ficar visíveis para outras pessoas, como uma chave de API externa, defina o tipo como Segredo ao adicionar o cabeçalho. Assim esse valor é guardado oculto e não fica exposto ao usuário final.

Aparência do menu suspenso de tipo aberto ao adicionar um cabeçalho. Escolhe-se entre Segredo, Autenticação básica HTTP e Personalizado

Executar um Script em vez de uma URL

Até aqui, o Webhook vinha enviando uma requisição para um endereço externo (URL). Em vez disso, o Webhook pode executar um Script criado dentro do Space. O Script é um mecanismo que realiza, dentro do Space e sem sair para fora, as tarefas que você definiu (criar e alterar recursos, entre outras). Você usa esse modo quando quer concluir as tarefas de bastidor dentro do Space, sem passar por um programa externo.

Um único Webhook faz exatamente uma das duas coisas: enviar para um endereço externo ou executar um Script. Você define isso em Destino da requisição na tela de criação. Se escolher Inserir URL, ele envia a requisição para um endereço como antes; se, em vez disso, escolher um Script na lista, ele executa esse Script.

Ao escolher um Script, aparece junto o Run as, que define com a identidade de quem esse Script será executado. Você escolhe uma das duas opções.

Criador do Webhook (padrão): o "criado por" dos recursos criados ou alterados durante a execução fica registrado como a pessoa que criou o Webhook.
Usuário que dispara: fica registrado como o usuário que provocou aquela mudança.

Essa configuração apenas define a marca de "quem fez" que fica nos recursos; ela não amplia nem restringe o que o Script pode fazer. O alcance do que um Script pode fazer já é definido quando você cria esse Script.

A ordem para fazer a escolha na prática é a seguinte.

Na tela de criação, clique em Destino da requisição.
Na lista, escolha o Script a executar. É escolher um Script em vez de Inserir URL.
Em Run as, escolha a identidade. O padrão é Criador do Webhook.

Tela de criação de Webhook com o Script "Preencher descrição do produto" escolhido como destino da requisição. Aparência com a URL de chamada preenchida e o Run as apresentando as duas opções Criador do Webhook e Usuário que dispara

O que é um Script e como criá-lo é tratado em Script.

Criar o Webhook da loja de roupas

Agora você vai 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". Digamos que o endereço do programa externo que vai receber a requisição é https://example.com/translate.

Nas configurações do Space da loja de roupas, abra a tela do Webhook.
Pressione o botão Criar no canto superior direito.
No campo de nome, digite Aviso de tradução de produto novo. Esse nome serve para você reconhecer depois de qual Webhook se trata.
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.
No campo URL digite o endereço do programa externo que vai receber a requisição, https://example.com/translate.
Se você deixar Ativo ligado, ele envia requisições assim que for criado (Active). Para apenas testar por um tempo, deixe desligado (Inactive).
Pressione o botão Criar para criar o Webhook.

Tela de criação de novo Webhook. Aparência com nome, ativação, seleção de gatilho e URL preenchidos

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

Tela com "Aviso de tradução de produto novo" visível na lista de Webhook no estado Active

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 pode ser excluído.

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.
Script: trata de como criar a tarefa que roda dentro do Space e que o Webhook pode executar em vez de uma URL.
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.