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.
Contexto | Descrição |
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. |
Tratamento de erros
Quando ocorre um erro em um cenário com webhook:
O cenário para imediatamente se estiver configurado para execução imediata.
Se estiver programado, o cenário para após 3 tentativas com erro.
Se o cenário tiver um módulo "Webhook response", o erro será enviado para ele, que sempre é executado por último, a menos que o "auto commit" esteja ativado nas configurações.
Formatos de dados de entrada suportados
O Toolzz Connect suporta os seguintes formatos de dados de entrada:
Query string
Form data
JSON
Se um webhook receber dados na query string e no formulário ou JSON ao mesmo tempo, o sistema combinará todos os dados em um único pacote. Se houver dados duplicados, a query string terá prioridade e substituirá os dados dos outros formatos. Recomendamos evitar duplicar dados na query string, formulário e JSON.
Cabeçalhos de webhook
Para acessar os cabeçalhos do webhook, habilite a opção "Get request headers" nas configurações avançadas quando for criar ou adicionar um webhook.
Você pode extrair um valor específico de um cabeçalho usando as funções "map()" e "get()". No exemplo abaixo, uma fórmula extrai o valor do cabeçalho "authorization" do array Headers[]. A fórmula é usada em um filtro para comparar o valor extraído com um texto específico, permitindo que o webhook passe apenas se houver correspondência.
Respondendo a webhooks
A resposta padrão para uma chamada de webhook é um texto simples: "Accepted". Essa resposta é enviada imediatamente ao chamador durante a execução do módulo "Custom Webhook". Para testar isso, siga os passos abaixo:
1º passo: no módulo Custom Webhook copie a URL do webhook.
2º passo: salve e execute o cenário – o módulo "Custom Webhook" ficará aguardando a chamada.
3º passo: abra uma nova janela do navegador, cole a URL na barra de endereços e pressione Enter.
O módulo Custom Webhook será acionado e o navegador mostrará a seguinte página:
Essas são as respostas padrão quando o cenário não inclui o módulo Webhook Response:
| Código de status HTTP | Body |
Webhook aceito na fila | 200 |
|
Fila de webhook cheia | 400 | Queue is full (a fila está cheia). |
Para personalizar a resposta do webhook, use o módulo Webhook Response. Ele possui dois campos: Status e Body.
O campo Status deve incluir códigos de status HTTP, como:
2xx para sucesso (exemplo: 200 para OK);
3xx para redirecionamento (exemplo: 307 para redirecionamento temporário);
4xx para erros do cliente (exemplo: 400 para solicitação inválida).
O campo Body pode conter qualquer formato aceito pelo webhook, como texto simples, HTML, XML ou JSON. É recomendável definir o cabeçalho Content-Type de acordo com o tipo de conteúdo que você está enviando, como:
text/plain para texto simples;
text/html para HTML;
application/json para JSON;
application/xml para XML.
Estas são respostas padrão adicionais quando o cenário contém o módulo "Webhook Response":
| Código de status HTTP | Body |
O cenário encontra um erro | 500 | O cenário não foi concluído. |
O tempo limite para enviar uma resposta é de 40 segundos. Se a resposta não for enviada dentro desse prazo, o Toolzz Connect retornará o status "200 Accepted".
Exemplo de resposta HTML
Configure o módulo "Webhook Response" da seguinte forma:
Status | 2xx código de status HTTP de sucesso, por exemplo, 200. |
Body | Código HTML, por exemplo: <!DOCTYPE html > |
Custom headers | Key Content-type Value text/html Ele produzirá uma resposta HTML que será exibida assim em um navegador da web: "Thank you |
Exemplo de redirecionamento
Configure o módulo "Webhook Response" da seguinte forma:
Status | Código de status HTTP de redirecionamento 3xx , por exemplo 303 |
Custom headers | Key Location Value A URL para a qual você gostaria de redirecionar. |
Mailhook personalizado
O Mailhook é um módulo de gatilho instantâneo acionado quando você envia um e-mail para o endereço gerado pelo módulo.
❗Informação importante: o tamanho máximo de um e-mail, incluindo seus anexos, que você envia para um mailhook é de 25 MB.
Exemplo de Uso
O Mailhook monitorará seus e-mails recebidos sem a necessidade de uma execução agendada do cenário.
1º passo: adicione ao seu cenário o módulo de Webhook "Custom mailhook".
Adicione um endereço de e-mail mailhook e copie o endereço que será gerado.
2º passo: salve e execute o cenário.
3º passo: para finalizar, abra as configurações da sua conta de e-mail e configure o encaminhamento. Use o endereço de e-mail gerado pelo módulo "Custom mailhook" no endereço de encaminhamento.
Para configurar o redirecionamento de e-mails no Gmail, siga os passos do artigo Encaminhar as mensagens do Gmail automaticamente para outra conta.
Depois da configuração, toda vez que um novo e-mail for recebido em sua conta de e-mail, o módulo "Custom mailhook" será acionado e receberá os dados da mensagem de e-mail.
💡Dica
Os endereços do remetente e dos destinatários (Para: CC e BCC) são capturados na estrutura de dados do e-mail recebido. O campo Reply-To pode ser encontrado na seção de cabeçalhos (Header).
Limite de taxa de Webohook
O Toolzz Connect pode processar até 30 solicitações de webhook recebidas por segundo.
Se você enviar mais de 30 solicitações por segundo, o sistema retornará um erro com código de status 429.
Solução de problemas
Itens ausentes no painel de mapeamento
Se faltarem itens no painel de mapeamento após configurar o módulo "Custom Webhook" , clique no módulo e, em seguida, selecione "Re-determine data structure".
Em seguida, siga as instruções da seção "Criando webhooks personalizados" deste artigo.
Pronto! Agora você já sabe tudo sobre o módulo "Webhook" do Toolzz Connect.