Webhook
Essa ação permite que você faça uma solicitação HTTP para qualquer serviço externo que desejar. Isso é útil para enviar informações do bot para outro serviço ou para buscar informações de outro serviço e usá-las no bot.
Antes de utilizar essa ação, você precisará de conhecimento técnico sobre [solicitação HTTP e seus parâmetros] (https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview).
Como essa ação funciona
Aqui estão algumas explicações sobre como essa ação funciona e suas limitações:
O bot sempre executa essa ação de forma síncrona, o que significa que ele aguarda até que a solicitação receba um resultado (sucesso ou falha) antes de prosseguir para a próxima etapa. Se você tiver várias ações de webhook, uma após a outra, elas serão executadas sequencialmente, não em lotes.
O tempo limite da consulta é definido internamente como 15 segundos. Qualquer consulta de longa duração falhará após esse período.
O bot continuará mesmo que sua ação de webhook falhe por qualquer motivo.
É sua responsabilidade lidar com a resposta, seja ela bem-sucedida ou não. Você precisará especificar variáveis para armazenar os resultados da solicitação. Em seguida, cabe a você usar essas variáveis posteriormente no bot, por exemplo, como uma condição em um bloco de escolha.
Como usar
Parâmetros da solicitação
O único parâmetro obrigatório é o URL. Você pode adicionar parâmetros de consulta diretamente a ele:
ou use o auxiliar:
Todos os outros parâmetros (cabeçalhos e corpo) são opcionais. Você pode adicioná-los usando a mesma lógica, usando os botões "add header" (adicionar cabeçalho) ou "add body" (adicionar corpo) no canto superior direito.
Você pode inserir variáveis para enviar informações armazenadas anteriormente em qualquer campo: URL, parâmetros, cabeçalho ou corpo. Basta clicar no pequeno botão de variável à direita.
Depois de escolher o método correto, você pode clicar no botão Testar URL. Se a solicitação for bem-sucedida, um pequeno botão de "olho" no lado direito será exibido, permitindo que você dê uma olhada rápida no layout da resposta:
Erros de validação de solicitação
Ao configurar e testar a ação, você pode encontrar diferentes tipos de erros:
Processamos suas solicitações em nosso servidor e identificamos erros comuns:
| Tipo | razões | Ação |
|---|---|---|
| MissingParameter | Url ou método ausente | Verifique novamente se o URL e o método estão especificados corretamente. |
| BadRequest | URL, corpo, parâmetros ou cabeçalho inválidos | Verifique a validade de cada parâmetro. Use clientes como o Postman para verificar seus parâmetros. |
| BadResponse | Status da resposta diferente de 200 ou a resposta não está no formato JSON | Verifique o status de seu servidor. |
| KeyError | O caminho especificado não corresponde à carga útil da resposta | Verifique novamente a validade do caminho que você inseriu na ação do webhook para cada variável |
Analisar e armazenar a resposta das solicitações em variáveis
Quando sua solicitação receber uma resposta bem-sucedida, você poderá escolher uma variável que armazenará o resultado. Você também pode selecionar a parte da resposta que deseja armazenar usando o auxiliar "path" (caminho):
Se estiver tentando selecionar um arranjo (array) como valor, o helper sugerirá o uso da função flatMap, que lhe dá a possibilidade de extrair qualquer valor dele.
Por exemplo, digamos que a estrutura de dados da resposta de sua solicitação seja semelhante a esta:
{
"products": [
{
"id": 1,
"title": "iPhone 9",
"description": "Um celular da apple que não é nada parecido com a apple",
"price": 549,
"rating": 4.69,
"estoque": 94,
"marca": "Apple",
"category": "smartphones",
"images": [
"https://cdn.dummyjson.com/product-images/1/1.jpg",
"https://cdn.dummyjson.com/product-images/1/2.jpg"
]
},
{
"id": 2,
"title": "iPhone X",
"description": "Sem SIM, modelo A19211 Tela Super Retina HD de 6,5 polegadas com tecnologia OLED Chip A12 Bionic com ...",
"price": 899,
"rating": 4.44,
"estoque": 34,
"marca": "Apple",
"category": "smartphones",
"images": [
"https://cdn.dummyjson.com/product-images/2/1.jpg"
]
}
]
}
E você deseja armazenar na variável webhook success um array somente de títulos de produtos:
["iPhone 9", "iPhone X"]
O uso do valor a seguir atenderá às suas necessidades:
Se quiser acessar a categoria do segundo item do produto, você pode usar esse caminho:
products[1].category
Você pode armazenar várias partes da resposta em diferentes variáveis. Isso evitará que você execute a mesma solicitação de webhook várias vezes
Lidando com solicitações com falha
É possível que, mesmo depois de configurar corretamente sua ação de webhook, ela falhe ocasionalmente (erros de servidor, parâmetros não tratados corretamente etc.).
Se o comportamento do seu bot depender do resultado da solicitação, é importante dar uma tratativa aos erros.
O bot armazenará todos os erros na variável que você especificou ou usará a variável last webhook failure:
Cabe a você tratar esse erro ou não. A melhor maneira é criar uma variável específica para cada webhook e, em seguida, verificar por meio de um bloco de opções se a variável contém uma mensagem:
Teste sua solicitação no simulador
Você deve sempre verificar se o seu bot está se comportando conforme o esperado por meio do simulador, garantindo que as solicitações bem-sucedidas e com falha sejam tratadas corretamente. Quando o simulador chegar a uma ação de webhook, ao contrário do bot real, ele fará uma pausa e solicitará que você especifique como deveria ser a solicitação:
- Sucesso falso: Ele solicitará um modal para especificar o payload da solicitação bem-sucedida. Em seguida, ele utilizará cada caminho que você especificou na ação do webhook para analisar e armazenar as variáveis correspondentes. Observe que, se você estiver armazenando em uma variável do tipo lista, o simulador esperará que o payload fornecido contenha um arranjo no caminho correto. Caso contrário, será exibido um erro no modal, impedindo a continuidade.
Falha falsa: Exibirá o mesmo modal e permitirá que você especifique o payload a ser salvo na variável de falha especificada na ação.
Trigger real webhook: fará proxy de sua solicitação para o nosso servidor e retornará o resultado real. Isso pode ser útil para verificar se tudo está funcionando bem, mas lembre-se de que ele fará uma solicitação HTTP real. Se você planeja adicionar um usuário ao seu CRM por meio da ação do webhook, usar essa opção no simulador pode adicionar dados indesejados ao seu CRM.