Webhooks são um mecanismo de envio automático de dados entre sites e aplicativos quando determinados eventos ocorrem. Os dados são transmitidos por meio de uma requisição HTTP: um aplicativo os envia pela Internet a um endereço de outro aplicativo definido previamente.
Possibilidades dos webhooks
No FLOWIN, os webhooks funcionam com encaminhamentos. Eles podem ser acionados quando uma mensagem é criada, editada, excluída ou fixada no chat de origem, assim como quando um botão é pressionado no chat para o qual as mensagens são encaminhadas (destino).
Assim, você pode conectar o FLOWIN a redes sociais, bolsas, planilhas e sistemas de CRM (sistemas de gestão de relacionamento com clientes). Essa conexão é chamada de integração e permite:
- Adicionar automaticamente solicitações do Telegram a um CRM.
- Enviar sinais de negociação do Telegram para uma bolsa para que as operações sejam copiadas automaticamente, ou seja, realizadas de forma automática com base nesses sinais.
- Encaminhar mensagens do Telegram para outras redes sociais.
- Copiar posts e mensagens para o Planilhas Google.
- Configurar respostas automáticas em um bot.
Para cada cenário, é preciso configurar o recebimento dos dados e a ação desejada no site ou aplicativo.
Criação de um webhook
Vamos testar o webhook no webhook.site, que fornece um endereço para receber dados e exibe as requisições recebidas. Enviaremos a ele o texto de uma nova mensagem do Telegram.
Para isso, é preciso ter um encaminhamento configurado e funcionando no FLOWIN.
Para o primeiro teste
Use um chat de teste separado e uma solicitação fictícia. Para a verificação, basta enviar o texto, sem nomes, telefones ou outros dados pessoais.
Abra @flow_in_bot, envie o comando
/starte clique em “Painel de controle”.
Acesso ao painel de controle pelo @flow_in_bot. Abra o webhook.site em outra aba. Copie o endereço para receber requisições do campo “Your unique URL”.
Endereço para receber a requisição de teste. No painel do FLOWIN, abra “Menu” → “Webhooks” e clique em “Criar”.
Seção “Webhooks” no menu do FLOWIN. 
Criação do primeiro webhook. Cole o endereço copiado no campo superior. No campo “Corpo da requisição”, insira
{"message":"<message-text>"}e clique em “Criar”. Esse é o modelo dos dados enviados: no lugar de<message-text>o FLOWIN colocará o texto da mensagem, e o destinatário o verá no campomessage.
Endereço e corpo da requisição de teste. Clique em “Aplicar” ao lado do webhook criado. Marque o encaminhamento desejado e clique em “Salvar”.
Conexão do webhook a um encaminhamento. 
Seleção do encaminhamento para o webhook. Envie uma mensagem de teste ao chat de origem, por exemplo: “Solicitação nº 1042: preciso de um catálogo de móveis.” Volte ao webhook.site: a primeira requisição recebida será aberta automaticamente. No bloco “Request Content”, o texto da solicitação aparecerá no campo
message. Agora, o FLOWIN enviará automaticamente o texto de cada nova mensagem ao endereço indicado antes de encaminhá-la ao chat de destino.
Solicitação de teste no chat de origem. 
Texto da solicitação recebido no webhook.site.
Configurações dos webhooks
Vamos examinar as configurações usando o webhook criado como exemplo: como alterá-las e o que significa cada campo.
Onde encontrar as configurações
Para conectar outro site ou aplicativo, consulte a documentação dele. Em geral, as regras para recebimento de dados ficam na seção API, que descreve a interação com outros programas. Ela informa o endereço, o método HTTP e o formato dos dados para preencher os campos abaixo.
Como alterar as configurações do webhook
Na lista “Webhooks”, clique em “Alterar” ao lado do webhook desejado.
Abertura das configurações do webhook. Altere os campos desejados e clique em “Salvar”.
Salvamento das configurações alteradas. 
Descrição salva nas configurações do webhook.
Método HTTP
O método HTTP define a ação da requisição: POST envia dados para processamento, GET solicita dados e PUT os substitui. POST é a opção padrão e é adequada ao nosso teste. Para outro site ou aplicativo, selecione o método indicado na documentação dele.
Endereço URL
URL é um endereço na Internet. Aqui, você informa o endereço para receber dados fornecido pelo site ou aplicativo que está sendo conectado. No nosso exemplo, ele foi fornecido pelo webhook.site.
Corpo da requisição
O corpo da requisição contém os dados enviados em formato JSON: pares de “nome do campo: valor”. O conjunto de campos depende dos requisitos do site ou aplicativo que está sendo conectado.
Metatags são marcadores que o FLOWIN substitui pelos dados da mensagem. Por exemplo, <message-text> é substituído pelo texto, e <author-name> pelo nome do autor. A lista de metatags também pode ser aberta pelo link “metatags” abaixo do campo.
Os números de usuários, mensagens, chats e tópicos na lista abaixo são seus identificadores (IDs) no Telegram.
Mensagem e autor
- Texto da mensagem:
<message-text>. - Data da mensagem:
<message-date>. - Hora da mensagem:
<message-time>. - Número do autor:
<author-id>. - Nome do autor:
<author-name>. - Nome do autor em um link HTML para o perfil dele:
<author-name-link>. - Nome do autor como hashtag:
<author-name-tag>. - Nome de usuário do autor:
<author-username>.
Origem
- Texto da mensagem:
<src-message-text>. - Número da mensagem:
<src-message-id>. - Link da mensagem:
<src-message-link>. - Número do chat:
<src-chat-id>. - Nome do chat:
<src-chat-name>. - Nome de usuário do chat:
<src-chat-username>. - Número do tópico:
<src-topic-id>. - Nome do tópico:
<src-topic-name>.
Destino
- Texto da mensagem:
<dst-message-text>. - Número da mensagem:
<dst-message-id>. - Link da mensagem:
<dst-message-link>. - Número do chat:
<dst-chat-id>. - Nome do chat:
<dst-chat-name>. - Nome de usuário do chat:
<dst-chat-username>. - Número do tópico:
<dst-topic-id>. - Nome do tópico:
<dst-topic-name>.
O número e o link da mensagem no destino ficam disponíveis após o encaminhamento. Para enviá-los, selecione “Após o envio” no campo “Gatilho da requisição”.
Clique no botão
- Número do usuário que clicou:
<clicker-id>. - Nome do usuário que clicou:
<clicker-name>. - Dados do botão:
<clicker-data>. - Data do clique:
<click-date>. - Hora do clique:
<click-time>.
Seleção de texto
- Uma expressão regular define uma regra de busca de texto. Por exemplo,
<regexp>(short|sell)</regexp>insere a primeira correspondência encontrada parashortousell. - Texto aleatório
<random>1|2|3|4|5</random>insere uma das cinco opções. Entre as tags, você pode indicar suas próprias opções, separando-as pelo símbolo|.
Cabeçalhos da requisição
Os “Cabeçalhos da requisição” contêm informações técnicas para o destinatário. Por exemplo, uma chave de acesso permite verificar quem enviou a requisição. Os cabeçalhos são definidos em formato JSON. Em geral, não é necessário alterar esse campo; os valores necessários são obtidos na documentação do site ou aplicativo que está sendo conectado.
Gatilho da requisição
O “Gatilho da requisição” define o evento e o momento em que o webhook deve enviar a requisição ao endereço indicado. Você pode selecionar os seguintes eventos:
- “Envio” é a opção padrão. O webhook é acionado ao encaminhar uma nova mensagem.
- “Edição” é acionado ao processar a edição de uma mensagem na origem.
- “Fixação” é acionado ao processar a fixação de uma mensagem na origem.
- “Exclusão” é acionado ao processar a exclusão de uma mensagem na origem.
- “Clique no botão” é acionado por botões de callback no chat de destino. Esse tipo de botão informa ao bot que houve um clique e envia os dados definidos para ele. Um botão comum com link não aciona esse webhook.
O momento do envio define em qual etapa do encaminhamento a requisição será enviada:
- “Antes do processamento”: a requisição é enviada antes da tradução e do processamento da mensagem por inteligência artificial (IA).
- “Após o processamento”: a requisição é enviada após a tradução e o processamento com IA.
- “Após o envio”: a requisição é enviada quando a mensagem já foi enviada ou editada com sucesso no chat de destino.
Momentos de envio disponíveis
As três opções estão disponíveis para os eventos “Envio” e “Edição”. Para “Fixação”, “Exclusão” e “Clique no botão”, é usado “Antes do processamento”, e não é possível selecionar outro momento.
Descrição
A “Descrição” serve como comentário para sua conveniência e não afeta o funcionamento do webhook. O campo pode ficar vazio.
Ações disponíveis para um webhook
Você pode gerenciar os webhooks criados pela lista “Webhooks”:
- “Alterar” abre as configurações principais do webhook.
- “Duplicar”, no menu “Mais”, cria uma cópia das configurações do webhook.
- “Selecionar projeto”, no menu “Mais”, adiciona o webhook a um projeto.
- “Excluir”, no menu “Mais”, exclui o webhook.
Além disso, cada webhook tem um botão “Encaminhamentos [N]”, que abre a seleção dos encaminhamentos aos quais ele se aplica. N representa a quantidade de encaminhamentos selecionados. Se nenhum encaminhamento tiver sido selecionado, aparecerá o botão “Aplicar” no lugar dele.
Perguntas frequentes
O que é um webhook em palavras simples?
É uma forma de enviar dados automaticamente a outro aplicativo quando ocorre um determinado evento. Por exemplo, ao encaminhar uma nova mensagem, o FLOWIN envia o texto dela ao endereço que você indicou por meio de uma requisição HTTP. Aqui, quem envia a requisição é o FLOWIN; o método do Telegram setWebhook configura outro sentido: a entrega de atualizações do Telegram ao programa que opera o bot.
Basta informar o endereço do CRM?
Não. É necessário usar o endereço para receber dados indicado na documentação do CRM, além do método HTTP, dos campos JSON e dos cabeçalhos adequados, caso sejam exigidos para o acesso. O endereço comum do site do CRM não serve para isso. O FLOWIN envia a requisição, enquanto a criação da solicitação ou outra ação depende de como o CRM processa os dados recebidos. Os valores dos campos estão descritos na seção “Configurações dos webhooks”.
Por que o link da mensagem no destino está vazio?
Antes de uma nova mensagem ser enviada com sucesso, o FLOWIN ainda não tem o número nem o link dela no destino. Para enviar <dst-message-id> e <dst-message-link> selecione o evento “Envio” ou “Edição” e o momento “Após o envio” no campo “Gatilho da requisição”. O link é gerado para canais e supergrupos. No caso de um chat privado ou de um grupo comum, <dst-message-link> permanecerá vazio mesmo após o envio.
É possível acionar um webhook clicando em um botão de URL comum?
Não. Um botão de URL comum abre um link. Para o evento “Clique no botão”, é necessário um botão de callback no chat de destino: ele envia ao bot os dados do clique. Essa diferença está descrita na seção “Gatilho da requisição”.
Como verificar se o serviço externo recebeu os dados?
Envie uma mensagem fictícia e confira a requisição recebida no serviço. No exemplo com webhook.site o texto da solicitação aparece no bloco “Request Content”. O sucesso do encaminhamento no Telegram, por si só, não confirma que o serviço externo recebeu os dados ou executou a ação desejada. Para a verificação, basta usar o texto, sem nomes, telefones ou outros dados pessoais.