Webhooks

Beta

Este produto ou recurso está em estado de pré-lançamento, podendo ser alterado ou ter suporte limitado. Para mais informações, consulte as etapas de lançamento do produto .

Webhooks são serviços que hospedam sua lógica de negócios. Durante uma sessão, os webhooks permitem que você use os dados extraídos pelo processamento de idioma natural do Dialogflow para gerar respostas dinâmicas, validar dados coletados ou ativar ações no back-end.

Os webhooks do CX são semelhantes aos webhooks do ES, mas os campos de solicitação e resposta foram alterados para oferecer suporte aos recursos do CX.

Requisitos de serviço do webhook

Os seguintes requisitos devem ser atendidos pelo serviço do webhook:

• Ele precisa processar solicitações HTTPS. O HTTP não é compatível. Se você hospedar seu serviço de webhook no Google Cloud Platform usando uma solução de computação ou computação sem servidor, consulte a documentação do produto para veiculação com HTTPS. Para conhecer outras opções de hospedagem, consulte Adquira um certificado SSL para seu domínio.
• Seu URL para solicitações deve ser acessível publicamente.
• Ele precisa processar solicitações POST com um corpo JSON WebhookRequest.
• Ele precisa responder a solicitações WebhookRequest com um corpo JSON WebhookResponse.

Autenticação

É importante proteger seu serviço de webhook para que somente você ou seu agente do Dialogflow sejam autorizados a fazer solicitações. Isso é configurado ao criar um recurso de webhook. O Dialogflow CX é compatível com os seguintes mecanismos de autenticação:

• Autenticação com cabeçalhos de autenticação.
• Autenticação TLS mútua.

Solicitação de webhook

Quando um fulfillment com um webhook é chamado, o Dialogflow envia uma solicitação de webhook POST HTTPS para seu serviço de webhook. O corpo dessa solicitação é um objeto JSON com informações sobre a intent correspondente.

Observação: a documentação REST JSON para esse tipo deve ser a referência principal, porque esse tipo é enviado somente por meio do protocolo REST JSON. Devido a um bug interno de geração de documentação, a documentação para esse tipo não pode ser produzida para REST. Consulte as descrições dos campos na documentação da RPC e traduza para JSON até que esse bug seja resolvido.

Consulte a documentação de referência de WebhookRequest para mais detalhes.

Resposta do webhook

Uma vez que seu serviço de webhook recebe uma solicitação de webhook, ela precisa enviar uma resposta a um webhook. As seguintes limitações se aplicam à sua resposta:

• A resposta precisa ocorrer dentro de um tempo limite que você configura ao criar o recurso de webhook. Caso contrário, a solicitação atingirá o tempo limite.
• É necessário que o tamanho da resposta seja menor ou igual a 64 KiB.

Observação: a documentação REST JSON para esse tipo deve ser a referência principal, porque esse tipo é enviado apenas pelo protocolo REST JSON. Devido a um bug interno de geração de documentação, a documentação para esse tipo não pode ser produzida para REST. Consulte as descrições dos campos na documentação da RPC e traduza para JSON até que esse bug seja resolvido.

Consulte a documentação de referência de WebhookResponse para mais detalhes.

Criar um recurso de webhook

Depois de ter um serviço de webhook em execução, você precisa criar um recurso de webhook no agente que tenha informações de conectividade e autenticação. Para criar um recurso de webhook:

Console

1. Abra o Console do Dialogflow CX.
2. Escolha seu projeto do GCP.
3. Selecione seu agente.
4. Selecione a guia Gerenciar.
5. Clique em Webhooks.
6. Clique em Criar
7. Insira os dados do webhook.
8. Clique em Save.

API

Veja o método create na referência do webhook

Selecione um protocolo e uma versão para a referência do Webhook:

Protocolo	V3beta1
REST	Recurso Webhook
RPC	Webhook interface

Fechar

Erros de webhook

Se o serviço de webhook encontrar um erro ao processar uma solicitação do webhook, o código do webhook retornará um dos seguintes códigos de status HTTP:

• 400 Solicitação inválida
• 401 Não autorizado
• 403 Proibido
• 404 Não encontrado
• 500 Falha no servidor
• 503 Serviço não disponível

Em qualquer uma das situações de erro a seguir, o Dialogflow invoca um erro de webhook ou evento integrado de tempo limite e continua processando normalmente:

• Tempo limite de resposta excedido.
• Código de status de erro recebido.
• A resposta é inválida.
• O serviço de webhook não está disponível.

Além disso, se a chamada de serviço do webhook tiver sido acionada por uma chamada de API de intent de detecção, o campo queryResult.webhookStatuses na resposta de intent de detecção conterá as informações de status do webhook.