Nesse artigo você encontrará as seguintes informações:

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.

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 o URL do webhook receber uma solicitação.

O Toolzz Connect suporta os seguintes tipos de webhooks:

Muitos aplicativos fornecem webhooks para executar cenários sempre que uma determinada alteração ocorre no aplicativo. Estes são chamados de gatilhos instantâneos (instant triggers). Os gatilhos instantâneos 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.

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. Você não pode usar um webhook em vários cenários.

1º passo: pesquise e selecione o aplicativo "Webhook".

2º passo: insira o módulo "Custom Webhook" do aplicativo Webhooks.

3º passo: nas configurações do módulo, clique em "Create a webhook".

4º passo: defina o nome do webhook e outras configurações 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 esta URL para a plataforma determinar, automaticamente, a estrutura de dados para este webhook. Consulte a configuração da estrutura de dados do webhook abaixo para obter mais detalhes.

Opcionalmente, você pode deixar o Toolzz Connect saber qual estrutura de dados esperar na carga de solicitação do webhook.

A plataforma pode usar estruturas de dados para validar os dados recebidos. Se você não configurar uma estrutura de dados, o Toolzz Connect passará os dados recebidos para os módulos subsequentes em seu cenário sem qualquer validação.

Para habilitar a validação de dados de entrada, configure a estrutura de dados do webhook de uma das seguintes maneiras:

Você também pode usar os métodos a seguir para informar ao Toolzz Connect qual estrutura de dados esperar.

⚠️ Aviso

Observe que esses métodos não permitem a validação de dados. A estrutura de dados configurada dessa maneira apenas ajuda a mapear os dados do webhook para os módulos subsequentes em seu cenário.

Se você chamar a URL do webhook para determinar ou redeterminar automaticamente a estrutura de dados, o Toolzz Connect não criará uma estrutura de dados reutilizável na seção Estruturas de dados (Data structures). A estrutura de dados determinada dessa maneira é armazenada internamente com o webhook específico. Nesse caso, a plataforma não valida os dados recebidos.

Por padrão, quando o Toolzz Connect recebe dados em um webhook, seu cenário é executado imediatamente. Se não quiser executar seu cenário imediatamente após um webhook receber dados, você pode agendar seu cenário para processar todas as solicitações de webhook periodicamente.

1º passo: edite o cenário que é acionado pelo seu webhook.

2º passo: edite as configurações de agendamento do cenário. Ou edite as configurações de agendamento do módulo webhook.

3º passo: configure a programação desejada.

Quando um webhook agendado recebe dados, o Toolzz Connect armazena os dados na fila do webhook. A fila inteira é então processada toda vez que seus critérios de agendamento são atendidos.

Quando um webhook recebe uma solicitação, o sistema armazena a solicitação na fila do webhook. Cada webhook tem sua própria fila. Vá para a seção Webhooks no menu à esquerda para visualizar todos os webhooks e suas filas.

Se você estiver usando webhooks instantâneos, o Toolzz Connect começa a processar cada solicitação imediatamente quando a solicitação é recebida. Por padrão, os cenários com webhooks instantâneos são processados ​​em paralelo. Mesmo que a execução de um cenário anterior ainda esteja sendo processada, a plataforma não espera que seu processamento seja concluído.

Você pode inspecionar todas as execuções em execução no detalhe do cenário. Clique em um item na lista de execuções para visualizar a representação gráfica dessa execução específica. A execução atual exibida é marcada com um ícone de olho.

Para desativar o processamento paralelo, abra as configurações do seu cenário e selecione "Sequential processing". Com o processamento sequencial ativado, o Tool Connect espera até que a execução anterior seja concluída antes de iniciar a próxima. Além disso, use o processamento sequencial quando precisar processar suas solicitações de webhook na ordem em que elas chegaram.

Se você estiver usando webhooks agendados, as solicitações se acumularão na fila até que os critérios de agendamento sejam atendidos. Quando os critérios de agendamento são atendidos, o Toolzz Connect processa as solicitações enfileiradas com base no número máximo de resultados (Maximum number of results) que você define para o webhook.

Por exemplo, se seu cenário estiver planejado para ser executado a cada hora e seu Número máximo de resultados estiver definido como o valor padrão de 2, o Toolzz Connect processará dois itens da fila a cada hora. Se sua fila de webhook estiver cheia de solicitações, aumente o número máximo de resultados ou ajuste o agendamento para executar o cenário com mais frequência.

❗ Observação

Os Instant trigger (módulos de disparo instantâneo) têm o parâmetro "Maximum number of cycles" em vez do "Maximum number of results".

Defina o Número máximo de ciclos nos módulos de disparo instantâneo para obter o mesmo comportamento de processamento de dados com webhooks e o parâmetro Número máximo de resultados.

Quando os dados chegam a um webhook e a chamada não é processada instantaneamente, o Toolzz Connect armazena-os na fila de processamento 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:

Basic - 5000

Standard - 7000

Deluxe - 10000

Quando a fila do webhook está cheia, a plataforma rejeita todos os dados de webhook de entrada que estão acima do limite.

Os dados de webhook recebidos são sempre armazenados na fila, independentemente das configurações da opção. Os dados são confidenciais. Assim que os dados são processados ​​em um cenário, eles são excluídos permanentemente.

1º passo: clique em "More" e depois em "Webhooks".

2º passo: encontre o webhook cuja fila você deseja visualizar.

3º passo: clique no webhook específico na lista para inspecionar seus detalhes.

Você pode ver:

4º passo: para ver a fila do webhook, clique em "Queue".

Você também pode clicar no botão com o ícone representado pelo desenho de um caminhão na página "Webhooks".

E a fila do webhook será exibida.

5º passo: clique no botão "Detail" referente ao webhook que você deseja inspecionar.

Você verá os itens analisados.

O Toolzz Connect desativa automaticamente os webhooks que não estão conectados a nenhum cenário há mais de 5 dias (120 horas). O hook retorna o código de status "410Gone".

1º passo: clique em "More" e depois em "Webhooks".

2º passo: clique no botão com o desenho de caminhão para ver a fila do webhook.

3º passo: marque o checkbox à esquerda na frente das entradas que deseja excluir.

4º passo: clique em "Delete selected" para excluir o ou os webhooks escolhidos.

Para excluir tudo, marque a primeira caixa à esquerda e, em seguida, clique em "Delete all".

5º passo: clique em "OK" para confirmar.

Você excluiu os itens de webhook recebidos da fila.

O Toolzz Connect armazena registros de webhook de acordo com o seu plano:

Basic - 7 dias

Standard - 30 dias

Deluxe - 60 dias

Para visualizar os logs do webhook, siga as etapas abaixo.

1º passo: vá para a seção "Webhooks" no menu à esquerda.

2º passo: clique no webhook específico na lista para inspecionar seus detalhes.

3º passo: clique em "Logs".

Nessa tela você vai ver:

4ª passo: para ver os detalhes do log de webhook específico, clique em "Detail".

Você verá:

Para ajustar as configurações de um webhook, clique em "Webhooks" no menu à esquerda e depois em "Edit a webhook".

Quando há um erro em seu cenário com um webhook, o cenário:

Se o seu cenário contiver um módulo "Webhook response", o erro será enviado para ele. O módulo de resposta do webhook é sempre executado por último, a menos que você habilite a confirmação automática nas configurações do cenário.

O Toolzz Connect suporta os seguintes formatos de dados de entrada:

Se um webhook receber dados na string de consulta e dados de formulário ou dados JSON ao mesmo tempo, o sistema combinará os dados em um único pacote. Se a solicitação contiver dados duplicados em formatos diferentes, a string de consulta terá prioridade e substituirá os dados recebidos nos outros formatos. Recomendamos que você não duplique dados em strings de consulta, dados de formulário e JSON.

Para acessar os cabeçalhos do webhook, habilite a opção "Get request headers" na configuração do webhook.

Você pode extrair um valor de cabeçalho específico com a combinação de funções "map()" e "get()". O exemplo abaixo mostra uma fórmula que extrai o valor do cabeçalho "authorization" da matriz "Headers[]". A fórmula é usada em um filtro que compara o valor extraído com o texto fornecido para passar apenas webhooks se houver correspondência.

Consulte Mapeando o elemento de um array com uma determinada chave para obter mais informações sobre como obter o elemento de um array com uma determinada chave.

A resposta padrão para uma chamada de webhook contém apenas um texto simples, "Accepted". A resposta é retornada ao chamador do webhook imediatamente durante a execução do módulo "Custom Webhook". Você pode facilmente testá-lo.

1º passo: coloque o módulo "Custom Webhook" em seu cenário.

2º passo: adicione um novo webhook na configuração do módulo.

3º passo: copie o URL do webhook para a área de transferência.

4º passo: execute o cenário. O módulo "Custom Webhook" deve estar aguardando a chamada do webhook.

5º passo: abra uma nova janela do navegador, cole o URL copiado na barra de endereços e pressione "Enter".

6º passo: o módulo "Custom Webhook" será acionado e o navegador exibirá a seguinte página:

Estas são as respostas padrão quando o cenário não contém o módulo "Webhook Response":

Se você deseja personalizar a resposta do webhook, use o módulo "Webhook Response". A configuração do módulo contém dois campos: "Status" e "Body".

O campo "Status" deve conter códigos de status de resposta HTTP como 2xx para sucesso (exemplo: 200 para OK), 3xx para redirecionamento (exemplo: 307 para redirecionamento temporário), 4xx para erros do cliente (por exemplo: 400 para solicitação inválida) etc. ser aceito pela chamada do webhook. Pode ser um texto simples, HTML, XML, JSON, etc. É aconselhável definir o cabeçalho para o tipo mime correspondente: "text/plain" para texto simples, "text/html" para HTML, "application/json" para JSON, "application/xml" para XML, etc.

Estas são respostas padrão adicionais quando o cenário contém o módulo "Webhook Response":

O tempo limite para enviar uma resposta é de 40 segundos. Se a resposta não estiver disponível dentro desse período, o Toolzz Connect retornará um status "200 Accepted".

Configure o módulo "Webhook Response" da seguinte forma:

Configure o módulo "Webhook Response" da seguinte forma:

Mailhook é um módulo de gatilho instantâneo que pode ser acionado enviando um e-mail para o endereço de e-mail gerado por este módulo.

❗ Observação

O tamanho máximo de um e-mail, incluindo seus anexos, que você envia para um mailhook é de 25 MB.

O Mailhook monitorará seus e-mails recebidos sem a necessidade de uma execução agendada do cenário.

1º passo: adicione o mailhook personalizado ao seu cenário (Webhooks > Custom mailhook).

2º passo: gere um endereço de e-mail mailhook e copie o endereço para a área de transferência.

3º passo: salve e execute o cenário.

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 2º passo como o endereço de encaminhamento.

1º passo: clique no ícone de engrenagem, localizado no canto superior direito da página e escolha a opção "Ver todas as configurações".

2º passo: abra a guia "Encaminhamento e POP/IMAP".

3º passo: Clique no botão "Adicionar um endereço de encaminhamento".

4º passo: digite o endereço de e-mail que você gerou e copiou no 2º passo e clique em "Próxima".

Uma janela pop-up aparecerá. Clique em "Continuar".

5º passo: um código de confirmação foi enviado para o seu mailhook. Você pode encontrar esse código em seu cenário na saída do módulo "Custom mailhook" em "Bundle > Text"

6º passo: insira o código de verificação nas configurações de encaminhamento da sua conta do Gmail e clique em "Confirmar".

7º passo: habilite o encaminhamento e salve as alterações.

Adicione outros módulos desejados ao cenário. Em seguida, salve e ative o cenário.

Agora, toda vez que um novo e-mail é recebido em sua conta de e-mail, o módulo "Custom mailhook" é acionado e recebe os dados da mensagem de e-mail.

❗ Observação:

O remetente e vários endereços de destinatários (Para: CC: e BCC:) são resolvidos na estrutura de dados do e-mail recebido. "Reply-To:" pode ser encontrado na seção "Header".

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 o código de status 429.

Se alguns itens estiverem faltando no painel de mapeamento, na configuração dos módulos seguindo o módulo "Webhooks > Custom Webhook", clique no módulo "Webhooks > Custom Webhook" para abrir sua configuração e depois clique em "Re-determine data structure".

Em seguida, siga as etapas descritas na seção "Criando webhooks personalizados" desse artigo.

Pronto! Agora você já sabe tudo sobre a ferramenta "Webhook" do Toolzz Connect.