APRENDENDO SOBRE WEBHOOKS DO TOOLZZ CONNECT - PARTE 1
Sobre
Os webhooks permitem que você envie dados para o Toolzz Connect através de HTTP. Os webhooks criam uma URL que você pode
chamar de aplicativo, serviço externo ou de outro cenário do Toolzz Connect.
Como funciona
Use webhooks para acionar a execução de cenários.
Os webhooks geralmente atuam como gatilhos instantâneos. Ao contrário dos gatilhos programados, que solicitam
periodicamente a um determinado serviço o processamento de novos dados, os webhooks executam o cenário imediatamente
após a URL do webhook receber uma solicitação.
O Toolzz Connect suporta:
- Os webhooks específicos do aplicativo, que detectam os dados provenientes de um aplicativo específico, também
chamados de gatilhos instantâneos.
- Os webhooks personalizados, que permitem que você crie uma URL para o qual você pode enviar quaisquer dados.
Criando webhooks específicos do aplicativo
Muitos aplicativos fornecem webhooks para executar cenários sempre que uma alteração ocorre no aplicativo. Estes são os
chamados "Gatilhos instantâneos" (instant triggers) e são marcados com o rótulo "INSTANT" na lista de módulos de um
aplicativo.
Se um aplicativo não fornecer webhooks, use gatilhos de pesquisa (polling triggers) para pesquisar periodicamente o
serviço em busca de novos dados.
Criando webhooks personalizados
Para criar um webhook, você deve inserir o módulo "Custom webhook" em um cenário.
🚩Observação: cada cenário deve usar seu próprio webhook. Não é possível usar um webhook em vários cenários.
Inserindo webhooks em cenários
1º passo: pesquise e selecione a opção "Webhook", depois insira o gatilho "Custom Webhook".
2º passo: nas configurações do módulo, clique no botão "Create a webhook".
Clique em "Add", defina o nome do webhook, se quiser realize configurações adicionais e clique em "Save".
O Toolzz Connect gera uma URL e começa a ouvir solicitações para essa URL. Envie uma solicitação para essa URL para que
a plataforma determine automaticamente a estrutura de dados para este webhook. Veja abaixo detalhes sobre a configuração
da estrutura de dados do webhook.
Configurando a estrutura de dados do webhook
Você pode informar ao Toolzz Connect qual estrutura de dados esperar na carga de solicitação do webhook.
A plataforma pode validar os dados recebidos com base na estrutura de dados. Se não configurar uma estrutura de dados, o
Toolzz Connect enviará os dados para os módulos subsequentes do cenário sem qualquer validação.
Para habilitar a validação, configure a estrutura de dados do webhook de uma das seguintes maneiras:
- Crie uma estrutura de dados manualmente na seção "Data structures section".
- Use uma estrutura de dados já existente.
Você também pode usar os métodos a seguir para informar ao Toolzz Connect qual estrutura de dados esperar:
- Crie uma estrutura de dados imediatamente após criar o webhook, chamando a URL do webhook com dados de amostra no
corpo da solicitação.
- Redefina a estrutura de dados de um webhook existente acessando as configurações do módulo, clicando em
"Re-determine data structure" e chamando a URL do webhook com dados de amostra no corpo da solicitação.
⚠️ Aviso
Esses métodos não permitem a validação de dados, apenas ajudam a mapear os dados do webhook para os módulos subsequentes
no cenário.
Ao usar a URL do webhook para determinar ou redefinir, automaticamente, a estrutura de dados, ela será armazenada
internamente com o webhook, sem ser reutilizável ou validada.
Agendamento de processamento de webhooks
Por padrão, quando o Toolzz Connect recebe dados via webhook, o cenário é executado imediatamente. Se preferir, você
pode programar o cenário para processar as solicitações de webhook em intervalos definidos, em vez de executá-lo na
hora.
Quando um webhook agendado recebe dados, o Toolzz Connect os armazena em uma fila. A fila inteira é processada sempre
que o critério de agendamento for atingido.
As configurações de agendamento são feitas através do botão com o desenho de um relógio, localizado no menu inferior da
tela de construção do cenário.
Para informações detalhadas acesse o artigo COMO AGENDAR UM CENÁRIO.
Como criar webhooks de processos
Quando um webhook recebe uma solicitação, ela é armazenada em sua própria fila. Cada webhook tem sua própria fila. Para
ver todos os webhooks e suas filas, acesse a seção "Webhooks" no menu lateral.
Processamento paralelo vs. sequencial
Com webhooks instantâneos, o Toolzz Connect processa cada solicitação assim que é recebida. Por padrão, cenários com
esses webhooks são executados em paralelo, ou seja, mesmo que uma execução anterior ainda esteja sendo processada, o
Connect não espera a conclusão para começar a próxima.
Você pode ver todas as execuções em andamento nos detalhes do cenário. Clique em uma execução para ver uma representação
gráfica dela. A execução que está sendo exibida no momento é marcada com um ícone de olho.
Você pode ver todas as execuções em andamento em "Currently Running", nos detalhes do cenário.
Para desativar o processamento paralelo, vá nas configurações do cenário e clique em "Yes" em "Sequential processing".
Com essa opção ativada, o Toolzz Connect espera a execução anterior terminar antes de iniciar a próxima. Use o
processamento sequencial quando precisar que os webhooks sejam processados na ordem em que chegam.
Processando webhooks programados
Com webhooks agendados, as solicitações ficam na fila até que o critério de agendamento programado seja atingido. Quando
isso acontece, o Toolzz Connect processa os itens da fila conforme o número máximo de resultados (Maximum number of
results) que você definiu para o webhook.
Por exemplo, se o cenário estiver programado para rodar a cada hora e o número máximo de resultados estiver definido
como 2, o Connect processará dois itens da fila por hora. Se a fila estiver acumulando muitas solicitações, você pode
aumentar o número de resultados ou ajustar a frequência do agendamento.
🚩Observação
Nos módulos de gatilho instantâneo (Instant trigger), o parâmetro é chamado de "Maximum number of cycles" em vez do
"Maximum number of results".
Defina o número máximo de ciclos nos gatilhos instantâneos para controlar o processamento de dados da mesma forma que
nos webhooks com o número máximo de resultados.
Detalhes da fila de webhook
Quando um webhook recebe dados e a chamada não é processada imediatamente, o Toolzz Connect os armazena na fila do
webhook.
O limite para o número de itens da fila de webhook depende de sua permissão de uso, que faz parte da sua assinatura.
Se a fila do webhook estiver cheia, o Toolzz Connect rejeitará os dados que excederem o limite.
Os dados recebidos sempre vão para a fila, mesmo com a opção "data is confidential" ativada. Assim que os dados são
processados, eles são excluídos permanentemente.
- Exibir fila de webhook
1º passo: acesse a opção "Webhooks" no menu lateral.
2º passo: encontre o webhook cuja fila você deseja visualizar. Clique no botão, com o ícone de desenho de um caminhão,
referente a ele.
3º passo: clique no botão "Detail" referente ao webhook que você deseja inspecionar e veja os itens analisados.
- Expiração de webhooks inativos
O Toolzz Connect desativa automaticamente webhooks que não estão conectados a nenhum cenário por mais de 5 dias (120
horas). Nesse caso, o webhook retorna o código de status "410 Gone".
"Este webhook expirou devido à inatividade porque não está conectado a nenhum cenário".
- Excluir item de webhook de uma fila
1º passo: encontre o webhook que deseja e clique no botão, com o ícone com o desenho de um caminhão, referente a ele.
2º passo: passe o mouse por cima do item que deseja excluir e veja que um ícone de checkbox ficará disponível. Marque o
checkbox do ou dos ícones que deseja excluir.
Se quiser selecionar todos os itens de uma vez, marque o checkbox no topo da lista.
Clique no botão "Delete selected" para excluir os itens selecionados ou "Delete all" caso queira excluir todos os itens.
- Registros (logs) de webhook
O Toolzz Connect armazena registros de webhook de acordo com o seu plano.
1º passo: clique na opção "Webhooks" no menu lateral.
2º passo: clique no webhook e depois acesse a aba "Logs".
Nessa aba estarão expostos:
- Status da chamada do webhook (sucesso, aviso, erro ou todos). Clique no ícone de funil para filtrar os resultados;
- Data e hora do webhook. Clique no ícone de seta para cima para classificar o log do webhook por data e hora;
- Tamanho do log de execução do webhook;
- Para ver os detalhes do log de webhook específico, clique em "Detail" e veja
- Solicitação de webhook (timestamp, URL, método, cabeçalhos, consulta, corpo);
- Resposta do webhook (status, cabeçalhos, corpo);
- Itens analisados, que combinam os parâmetros de consulta e o corpo da solicitação do webhook em um pacote.
Configurações do webhook
Para ajustar as configurações de um webhook, clique em "Webhooks" no menu lateral, escolha um webhook da lista e clique
no botão "Edit" com o ícone de uma folha e um lápis, referente a ele.
IP restrictions
Informe uma lista de endereços IP permitidos, separados por vírgula. Apenas solicitações vindas desses IPs serão
processadas. Use a notação CIDR para incluir sub-redes. Deixe em branco para aceitar solicitações de qualquer IP.
Data structure
Selecione uma estrutura de dados existente ou crie uma nova estrutura de dados para o webhook. O Toolzz Connect usará a
estrutura de dados para validar os dados recebidos. Solicitações que não passarem na validação serão rejeitadas com o
código de status HTTP 400.
Get request headers
Extrai dados de cabeçalhos da solicitação de webhook e disponibiliza os dados para mapeamento no cenário.
Get request HTTP method
Extrai o método HTTP da solicitação e disponibiliza o método para mapeamento no cenário.
JSON pass-through
Passa cargas JSON para módulos subsequentes no cenário como uma sequência de texto, em vez de dividir a carga em campos
mapeáveis.
Pronto! Agora você pode avançar para aprender mais sobre webhooks na segunda parte do artigo: APRENDENDO SOBRE WEBHOOKS
DO TOOLZZ CONNECT - PARTE 2
