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 JSONWebhookResponse
.
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.
- Como usar o Cloud Functions
- Tokens de identidade de serviç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.
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.
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
- Abra o Console do Dialogflow CX.
- Escolha seu projeto do GCP.
- Selecione seu agente.
- Selecione a guia Gerenciar.
- Clique em Webhooks.
- Clique em Criar
- Insira os dados do webhook.
- Clique em Save.
API
Veja o método create
para o tipo Webhook
.
Selecione um protocolo e uma versão para a referência do Webhook:
Protocolo | V3 | V3beta1 |
---|---|---|
REST | Recurso Webhook | Recurso Webhook |
RPC | Webhook interface | Webhook interface |
C# | Indisponível | Indisponível |
Go | Indisponível | Indisponível |
Java | WebhooksClient | WebhooksClient |
Node.js | WebhooksClient | WebhooksClient |
PHP | Indisponível | Indisponível |
Python | WebhooksClient | WebhooksClient |
Ruby | Indisponível | Indisponível |
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álida401
Não autorizado403
Proibido404
Não encontrado500
Falha no servidor503
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.
Como usar o Cloud Functions
O Dialogflow se integra ao Cloud Functions para que você crie facilmente um webhook seguro e sem servidor. Se você criar uma função que resida no mesmo projeto do agente, ele poderá chamar com segurança o webhook sem precisar de nenhuma configuração especial.
No entanto, há duas situações em que é preciso configurar essa integração manualmente:
- A conta de serviço
do agente de serviço do Dialogflow
com o endereço a seguir precisa existir para o projeto de agente:
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
Essa conta de serviço especial e a chave associada normalmente são criadas automaticamente quando você cria o primeiro agente de um projeto. Se o agente foi criado antes de 1º de novembro de 2020, a criação dessa conta de serviço especial pode ser acionada:- Crie um novo agente para o projeto.
- Execute o comando a seguir:
gcloud beta services identity create --service=dialogflow.googleapis.com --project=agent-project-id
- Se a função do webhook residir em um projeto diferente do agente, forneça o Papel do IAM Invocador do Cloud Functions à conta de serviço Agente de serviço do Dialogflow no projeto da função.
Tokens de identidade de serviço
Quando o Dialogflow chama um webhook, ele fornece um token de identidade do Google com a solicitação. Qualquer webhook pode, opcionalmente, validar o token usando bibliotecas de cliente do Google ou bibliotecas de código aberto, como em github.com/googleapis/google-auth-library-nodejs (em inglês).