Principal Webhooks APRENDENDO SOBRE WEBHOOKS DO TOOLZZ CONNECT - PARTE 2

APRENDENDO SOBRE WEBHOOKS DO TOOLZZ CONNECT - PARTE 2

Última atualização em Nov 01, 2024

Como já explicamos no primeiro artigo APRENDENDO SOBRE WEBHOOKS DO TOOLZZ CONNECT - PARTE 1 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.

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:

Webhook aceito na fila > Código de status HTTP 200 > Body Accepted (aceito).

Fila de webhook cheia > Código de status HTTP 400 > Body 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":

O cenário encontra um erro > Código de status HTTP 500 > Body 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 >
< html lang = "en" >
< head >
< meta charset = "UTF-8" >
< title > Obrigado! </ title >
</ head >
< body > Obrigado, {{1.name}}, pela sua solicitação!
</ body >
</ 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 name for your request!"

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.

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

Pronto! Agora você já sabe tudo sobre o módulo "Webhook" do Toolzz Connect.