WEBHOOKS - TOOLZZ CONNECT

Esse é um tutorial da plataforma Toolzz Connect

Eduardo avatar
Escrito por Eduardo
Atualizado há mais de uma semana

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

  • Criando webhooks específicos do aplicativo

  • Criando webhooks personalizados

  • Agendamento de processamento de webhooks

  • Como criar webhooks de processos

  • Configurações do webhook

  • Manipulação de erros

  • Formatos de dados de entrada suportados

  • Cabeçalhos de webhook

  • Respondendo a webhooks

  • Exemplo de resposta HTML

  • Exemplo de redirecionamento

  • Mailhook personalizado

  • Limite de taxa de webhook

  • Solução de problemas


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

O Toolzz Connect suporta os seguintes tipos de webhooks:

  • Os webhooks específicos do aplicativo detectam os dados provenientes de um aplicativo específico, também chamados de gatilhos instantâneos.

  • Os webhooks personalizados permitem que você crie um 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 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.


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

Inserindo webhooks em cenários

Passo a passo:

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.

Configurando a estrutura de dados do webhook

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:

  • Crie uma estrutura de dados manualmente na seção "Data structures section".

  • Use uma estrutura de dados existente.

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.

  • 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 Webhook, clicando em Re-determine data structure e chamando a URL do webhook com dados de amostra no corpo da solicitação.

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.


Agendamento de processamento de webhooks

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.

Passo a passo:

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.


Como criar webhooks de processos

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.

Processamento paralelo vs. sequencial

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.

Processando webhooks programados

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.

Detalhes da fila de webhook

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.

  • Exibir fila de webhook

Passo a passo:

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:

  • Status do webhook;

  • URL do webhook e UDID do webhook (identificador exclusivo do webhook);

  • Status do seu cenário;

  • ID do cenário e URL do cenário.

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.

  • Expiração de webhooks inativos

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".

  • Excluir item de webhook de uma fila

Passo a passo:

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.

  • Registros (logs) de webhook

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.

Passo a passo:

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:

  • Status da chamada do webhook (sucesso, aviso, erro ou todos)

    Para filtrar os logs do webhook por status, clique no ícone de filtro, representado por um funil.

  • Data e hora do webhook de entrada

    Para classificar o log do webhook por data e hora, clique no ícone de seta para cima.

  • Tamanho do log de execução do webhook

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

Você verá:

  • Solicitação de webhook (timestamp, URL, método, cabeçalhos, consulta, corpo);

  • Resposta do webhook (status, cabeçalhos, corpo);

  • Itens analisados. Esse itens ​​combinam os parâmetros de consulta e o corpo da solicitação de webhook em um pacote.


Configurações do webhook

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

Contexto

Descrição

IP restrictions

Uma lista branca de endereços IP delimitados por vírgula. Somente as solicitações de webhook provenientes dos IPs especificados serão processadas. Use a notação CIDR para colocar uma sub-rede na lista de permissões. Deixe em branco se quiser permitir solicitações de todos os IPs.

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. As 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 string de texto, em vez de dividir a carga em campos mapeáveis.


Manipulação de erros

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

  • Para imediatamente - quando o cenário está definido para execução imediata.

  • Para após 3 tentativas malsucedidas (3 erros) - quando o cenário está definido para ser executado conforme "scheduled".

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.


Formatos de dados de entrada suportados

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

  • Query string / Cadeia de consulta

  • Form data

  • JSON

  • dados do formulário

  • JSON

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.


Cabeçalhos de webhook

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.


Respondendo a webhooks

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.

Passo a passo:

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":

Código de status HTTP

Body

Webhook aceito na fila

200


Accepted (aceito).

Fila de webhook cheia

400

Queue is full (a fila está cheia).

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":

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 estiver disponível dentro desse período, o Toolzz Connect retornará um status "200 Accepted".


Exemplo de resposta HTML

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

Status

Body

Código HTML, por exemplo:

<!DOCTYPE html>

<html lang="en">

<head>

<meta charset="UTF-8">

<title>Thank you!</title>

</head>

<body>Thank you, {{1.name}}, for your request!

</body>

</html>

Custom headers

Key

Tipo de conteúdo

Value

texto/html

Ele produzirá uma resposta HTML que será exibida assim em um navegador da web:



Exemplo de redirecionamento

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

Status

Custom headers

Key

Localização

Value

A URL para a qual você gostaria de redirecionar.


Mailhook personalizado

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.

Exemplo de Uso

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

Passo a passo:

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.

Para Gmail

Passo a passo:

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".


Limite de taxa de webhook

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.


Solução de problemas

Itens ausentes no painel de mapeamento

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.

Respondeu à sua pergunta?