Como configurar requisições HTTP e Webhooks

A requisição HTTP serve como um mecanismo para notificações de eventos, permitindo que dados sejam transferidos de um sistema para outro.

Por exemplo, quando um possível cliente envia um comentário em um produto, uma notificação sobre esse comentário pode ser configurado para aparecer no chat do time responsável pelas vendas da empresa. Outro exemplo, seria quando um novo pedido é recebido, você pode precisar calcular o custo de entrega, ou quando a assinatura de um usuário está prestes a terminar, para isso, então, um alerta pode ser enviado para o sistema que sua empresa utiliza com essas informações.

Nestes exemplos e em milhões de outros cenários do dia a dia, uma configuração específica é preciso ser criada para permitir o envia dos dados corretamente.

Esse ajuste, é justamente a requisição HTTP, sendo esta, uma maneira de enviar para outras plataformas externas, as informações que desejamos.

Em outras palavras, uma requisição é enviada e os parâmetros (dados) necessários (assim como seu formato adequado) são enviados por meio dela.

Por exemplo, se você deseja criar um compromisso em alguma plataforma associado a algum usuário, precisará do ID do usuário, a data, hora, detalhes sobre o compromisso,e é claro, o endereço da plataforma para onde estamos enviando a solicitação.

Os dados obrigatórios irão sempre variar dependendo da ação que estamos querendo realizar após o envio da informação e também da plataforma para qual estamos enviando a requisição.

Alguns ajustes são padronizados, mas é importante estar sempre atentos as especificidades de cada App.

A URL, por exemplo, sempre deve estar presente e representa o endereço da ação e em qual plataforma será executada. Por exemplo, para a ação de criar um novo contato em uma plataforma X de exemplo, a URL seria esta: http://example.com/nofollow/create/contact, enquanto para a ação de atualizar um pedido nesta mesma plataforma, o endereço já seria este: http://example.com/nofollow/update/order.

Os cabeçalhos da requisição (Header) possuem características próprias, permitindo que o servidor receptor (plataforma externa) os processe corretamente.

Esses cabeçalhos, podem conter informações de login e senha para garantir a autorização no sistema onde estamos transferindo os dados. Apesar de variarem entre o que é obrigatório ou não entre as plataformas, na maioria das vezes, será exigido um cabeçalho com os dados de login, seja uma senha ou token gerados pela própria plataforma receptora para esse tipo de requisição.

O corpo da requisição (chamado de Body) contém informações sobre a próprio ação.

Ele inclui detalhes como quando ocorreu, quais campos foram preenchidos e seus valores correspondentes.

Os dados são sempre apresentados como pares nome do campo-valor, onde a "nome do campo" representa efetivamente o nome do campo na plataforma e o "valor" é o seu conteúdo.

Para configurar esses dados corretamente, é essencial entender a estrutura do objeto esperado e os dados que a ação requer. Exemplo: Se você tentar enviar um número, para um campo em uma plataforma externa que espera um texto, é possível acontecer um erro. O mesmo quando você envia um texto aberto, para um campo que espera opções de múltipla-escolha.

Os objetos podem ser simples ou ter formas compostas, juntas de outros objetos e/ou arrays.

Exemplo aqui seria os dados de endereço de uma casa. Em alguns casos, vemos um campo único com o endereço de uma residência, porém dentro deste campo, os dados complementares estarão individualmente separados por cidade, bairro, cep… entre outros.

Nesse cenário, o objeto "endereço" seria composto. Ou seja, possui outros objetos simples ou Arrays dentro dele.

Objetos são delimitados por chaves: "{objeto}," enquanto arrays são delimitados por colchetes: "[array]."

Para acessar as chaves de um objeto simples, basta especificar seus nomes. No entanto, para acessar as chaves dentro de objetos compostos, você deve usar "." para indicar o nome do objeto associado e, em seguida, o nome do objeto composto principal.

Da mesma forma, para arrays compostos, em vez de nomes, são usados números sequenciais começando por "0" para especificar o elemento desejado do array.

Objeto simples:

Objeto composto:

Objeto com array composto e dentro, outro objeto:

Não importa como os dados estão organizados, ao enviar uma requisição, existem diferentes formas de compacta-los.

Esse processo é importante e será determinado pelo método de requisição exigido pela plataforma receptora. Esta informação deve estar em um cabeçalho obrigatório na requisição indicando o chamado Content-type.

Falaremos agora sobre os métodos de requisição. Essa informação também é fundamental e deve estar presente na sua requisição.

Os dois métodos de requisição mais comuns são GET e POST e para simplificar, pense que para GET estaremos pedindo informações para a plafatorma externa.

Por outro lado, o POST é usado para enviar os dados para essa plataforma externa, vindos, de outro lugar.

Resumindo, ao enviar uma requisição, você deve ter a URL da acao que deseja criar na plataforma externa e os dados que ela espera receber.

Os dados são escritos nas chaves, e os nomes das chaves devem corresponder exatamente à estrutura do objeto que a ação espera. Não se esqueça de especificar o Content-type e o método para a requisição ser transmitida corretamente.

Para ter certeza do formato e de todas as informações necessárias sobre as configurações da requisição, você deve consultar a documentação API da plataforma externa a qual está enviando esta requisição.

Agora que você aprendeu na teoria o que é uma requisição HTTP, vamos colocar a mao na massa e aprender a parte prática.

Vá até a seção Apps e clique no botão Adicionar uma conexão.

Escolha o aplicativo de Requisição HTTP (HTTP Request) e clique no botão Adicionar uma conexão.

Em seguida, preencha os campos da Requisição HTTP.

É nesta etapa que será muito importante conhecer e ter em mãos, a documentação API da plataforma a qual está enviando os dados. Assim saberá quais campos são obrigatórios, seja no corpo (body) ou cabeçalho (Header).

Nome - Nome interno para facilitar seu uso na Albato;

URL - Endereço para onde a requisição, associada com a ação desejada, deve ser enviada;

Parâmetros da requisição HTTP (corpo da requisição) - Os parâmetros podem variar dependendo da ação a ser realizada. Uma lista completa dos campos necessários ou opcionais que podem/devem ser enviados, estará presente na documentação API da plataforma externa.

Se preferir, esta etapa pode ficar em branco também, sendo preenchida dentro da automação.

Cabeçalhos - Especifique o parâmetro de Autorização, o qual também será mencionado na documentação;

Content-Type - Apensar de poder variar, na maioria das vezes, se utiliza JSON.

Como percebemos, existe a possibilidade também de preencher os campos que serão enviados no corpo da requisição, além de adicionar os valores aos campos que configuramos no Header, dentro da automação.

Caso já tenha fornecido, por exemplo, a URL na etapa anterior, o campo de URL pode ficar em branco. O mesmo acontece para os campos de Content-Type e User-Agent.

Assim que o passo de HTTP for criado:

Ao clicar no passo de Http Request, você verá os campos configurados anteriormente em branco. Nesta etapa, você poderá adicionar os valores (e para os casos de campos no corpo da solicitação) o formato desse valor:

Neste exemplo da imagem, estamos enviando os dados de Nome, que possui um formato String e o campo de Telefone, no formato Decimal. Ambos dados foram coletados na primeira etapa da automação e ficam disponíveis, quando clicamos no campo em branco.

O formato do campo, assim como o nome do campo, também são informações que estarão disponíveis na documentação da plataforma externa a qual está enviando a requisição.

A conexão de Requisição HTTP oferece talvez a ferramenta mais flexível para transferir dados. Dependendo dos seus objetivos, a implementação dessa funcionalidade pode ser diferente, por isso, é sempre importante ter acesso a documentação da plataforma receptora.

URL - deixe vazio, o URL especificado no App será usado;

Método de solicitação - POST;

Cabeçalho User-Agent - Mozilla/5.0 (compatible; Albato/1.0);

Autorização (cabeçalho) - Basic, é o resultado da codificação da string "login:senha" com o algoritmo MIME base64 (por exemplo, para o login "admin" e a senha "password", o resultado será "YWRtaW46cGFzc3dvcmQ=");

Parâmetros - preencha os parâmetros que desejamos transferir para a solicitação HTTP.

A conexão de solicitação HTTP oferece talvez a ferramenta mais flexível para transferência de dados. Dependendo dos seus objetivos, a implementação da funcionalidade pode variar.

Um Webhook é um método alternativo e disponível se não houver uma conexão na Albato com o App que você gostaria de utilizar como gatilho da sua automação.

Ele funciona como um tipo de link que você vai adicionar na outra plataforma, e sempre que ele for acionado, ele enviará os dados para que você possa usá-los nas suas automações aqui na Albato.

Em outras palavras, você pode configurar o app externo para enviar certos dados sempre que uma ação específica ocorrer. Nesse caso, o primeiro passo é verificar com a equipe de suporte deles se eles aceitam esse método de conexão e como você pode configurá-lo na plataforma externa.

Se eles aceitarem, é muito simples do nosso lado.

O processo para adicionar uma conexao Webhook, é parecido a de qualquer outro aplicativo. Ao entrar na Aba de APPs da sua plataforma, procure por Incoming Webhook (webhook de entrada).

Ao criar uma conexão Webhook, você só precisa especificar o nome (título) da conexão.

Você também pode especificar parâmetros e cabeçalhos se souber com antecedência como eles são chamados no aplicativo onde os dados serão coletados. Esses parâmetros aparecerão na automação.

Após a criação, você terá uma URL do Webhook, que você deve colocar na plataforma externa. Caso tenha dúvidas de onde deve ser inserido, o suporte dessa plataforma externa poderá melhor te ajudar.

O botão "Esperar Webhook (ou em ingles, Wait a webhook)" é necessário para conexões de Webhook, quando você precisa capturar parâmetros de um serviço externo para usá-los na automação posteriormente.

Ele funcionará como uma forma de teste. Ao esperar o envio do Webhook, todos os parâmetros que forem enviados, agora ficarão disponíveis para serem usados nos passos a seguir.

Após criar a conexão, verá uma tela que automaticamente aparecerá com o link do Webhook. Caso já tenha inserido ele na plataforma externa, clique novamente em Esperar Webhook (wait Webhook)

Mantendo a nova tela que aparecerá aberta, vá até a plataforma externa onde o Webhook foi adicionado e se certifique de dispará-lo. Isso é, de realizar a ação a qual o Webhook está associado, que deve ser ativado, quando aconteça.

Todos os dados externos (nome dos campos) que forem enviados pelo Webhook por essa plataforma externa, irão aparecer nesta tela e estarão disponíveis para uso dentro das suas automações.

Caso sinta falta de algum, basta conhecer o nome deste campo e adicioná-lo corretamente diretamente na área de Parâmetros solicitados (Parametros Webhook), dentro da sua conexão de Webhook, na Aba de Apps da Albato.

Lembrando que aparecerão somente os nomes dos campos. Futuramente, quando utilizar em sua automação, poderá ver o valor presente nestes campos diretamente na sua aba de histórico da automação, logo após ela ser executada.

Caso tenha alguma dúvida em alguma das etapas, nosso time de suporte estará feliz em ajudá-lo!