Webhooks

Webhooks são serviços que hospedam sua lógica de negócios ou chamam outros serviços. 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.

Um webhook pode ser padrão ou flexível. Com um webhook padrão, os campos de solicitação e resposta são definidos pelo Dialogflow. Com um webhook flexível, você define os campos de solicitação e resposta.

Webhooks padrão

Com os webhooks padrão, você usa mensagens de solicitação e resposta definidas pelo Dialogflow. A mensagem da solicitação fornece muitos detalhes sobre a sessão. Por exemplo, página ativa atual, intent correspondente recente, valores de parâmetro de sessão e respostas definidas pelo agente são incluídos.

Solicitação de webhook padrão

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 da solicitação é um objeto JSON WebhookRequest com informações sobre a sessão.

Algumas integrações preenchem o campo WebhookRequest.payload com mais informações. Por exemplo, a integração do gateway de telefone do Dialogflow CX fornece o identificador de chamadas do usuário final.

Consulte a documentação de referência de WebhookRequest(V3) ou WebhookRequest(V3Beta1) para mais detalhes.

Resposta do webhook padrão

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(V3) ou WebhookResponse(V3Beta1) para mais detalhes.

Configurações padrão do recurso do webhook

Veja a seguir as configurações dos recursos de webhook para os webhooks padrão:

Termo Definição
Nome de exibição O nome do console mostrado para o webhook.
Tempo limite do webhook Quando o Dialogflow envia uma solicitação de webhook para o serviço de webhook, o tempo limite é atingido enquanto você aguarda uma resposta. Essa configuração controla esse tempo limite em segundos. Se ocorrer um tempo limite, o Dialogflow invocará um evento webhook.error.timeout.
Tipo Defina como Diretório de serviços se você estiver usando o diretório de serviço para acesso à rede privada. Caso contrário, defina como Serviço genérico da Web.
URL do webhook Informe o endereço do URL do seu serviço de webhook.
Subtipo Defina como Padrão.
Webhook específico do ambiente É possível fornecer webhooks específicos para ambientes.
Authentication Consulte a seção de autenticação.
Certificado de CA personalizado Isso é usado para fazer upload de certificados de CA personalizados.

Webhooks flexíveis

Com webhooks flexíveis, você define o método HTTP de solicitação, os parâmetros de URL de solicitação e os campos das mensagens de solicitação e resposta. A solicitação pode fornecer apenas valores de parâmetro selecionados, e a resposta pode fornecer apenas valores de substituição de parâmetro. Essa limitação é muito benéfica, porque simplifica a interface entre o agente e o webhook. Raramente é necessário comunicar algo além de valores de parâmetro de sessão entre um agente e um webhook. Isso também simplifica a implementação de webhook, porque as mensagens de solicitação e resposta contêm apenas o que você precisa, e você pode fornecer mensagens de webhook exclusivas para vários cenários.

Solicitação de webhook flexível

Ao criar o recurso de webhook para seu agente, é possível especificar o seguinte para solicitações de webhook:

  • O método HTTP usado para solicitações de webhook enviado para o serviço de webhook.
  • Valores de parâmetro de sessão que o Dialogflow precisa enviar para o serviço de webhook usando o URL.
  • Se você escolher POST, PUT ou PATCH como método, será possível especificar os valores de parâmetros de sessão que o Dialogflow deve enviar ao serviço de webhook por meio do corpo JSON da solicitação.

Para enviar valores de parâmetros de sessão usando o URL da solicitação ou o corpo JSON, use referências de parâmetros normalmente. Você não precisa usar escape de URL na referência do parâmetro e não a colocar entre aspas. No ambiente de execução, o Dialogflow fará o escape do valor do parâmetro conforme necessário. Uma lista ou um valor composto será fornecido como JSON.

Ao usar uma referência de parâmetro no corpo do JSON, é necessário colocar a referência entre aspas, independentemente do tipo de parâmetro. Se o parâmetro for, na verdade, um escalar numérico, uma lista ou um valor composto, o Dialogflow removerá as aspas ao enviar a solicitação no momento da execução para preservar o tipo de dados do parâmetro. Os tipos escalares de string continuarão entre aspas. Se um valor numérico de escala, lista ou composto for referenciado em um valor de string (por exemplo: "Este é um número: $session.params.size"), o parâmetro será tratado como uma string ("Este é um número: 3").

Por exemplo, forneça os valores de parâmetro de sessão fruit e size ao URL da solicitação desta maneira:

https://your-webhook-service.com/handler?f=$session.params.fruit&s=$session.params.size

E para o corpo JSON da solicitação, assim:

{
  "fruitParameter": "$session.params.fruit",
  "sizeParameter": "$session.params.size"
}

Resposta de webhook flexível

Ao criar o recurso de webhook para seu agente, é possível especificar parâmetros de sessão que o Dialogflow precisa definir para campos específicos da resposta do webhook no ambiente de execução.

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.

Use o seguinte formato para especificar um campo escalar, de lista ou composto:

$.fully.qualified.path.to.field

Por exemplo, considere a seguinte resposta JSON:

{
  "routes" : [
    {
      "legs" : [
        {
          "distance" : {
            "text" : "2,064 mi",
            "value" : 3321004
          }
        }
      ]
    }
  ]
}

Para especificar o campo "value", use o seguinte:

$.routes[0].legs[0].distance.value

Configurações flexíveis de recursos do webhook

Veja a seguir as configurações dos recursos de webhook para os webhooks flexíveis:

Termo Definição
Nome de exibição O nome do console mostrado para o webhook.
Tempo limite do webhook Quando o Dialogflow envia uma solicitação de webhook para o serviço de webhook, o tempo limite é atingido enquanto você aguarda uma resposta. Essa configuração controla esse tempo limite em segundos. Se ocorrer um tempo limite, o Dialogflow invocará um evento webhook.error.timeout.
Tipo Defina como Diretório de serviços se você estiver usando o diretório de serviço para acesso à rede privada. Caso contrário, defina como Serviço genérico da Web.
URL do webhook Informe o endereço do URL do serviço de webhook, que pode incluir referências a parâmetros de sessão.
Subtipo Defina como Flexível.
Método Defina o método HTTP para a solicitação do webhook.
Corpo da solicitação Forneça o corpo JSON da solicitação conforme descrito acima.
Configuração de resposta Informe os parâmetros da sessão que devem ser definidos nos campos de resposta conforme descrito acima.
Webhook específico do ambiente É possível fornecer webhooks específicos para ambientes.
Authentication Consulte a seção de autenticação.
Certificado de CA personalizado Isso é usado para fazer upload de certificados de CA personalizados.

Requisitos de serviço do webhook

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

Authentication

É 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:

Termo Definição
Nome de usuário e senha do login Para as configurações do webhook, especifique valores opcionais de nome de usuário e senha de login. Se fornecido, o Dialogflow adicionará um cabeçalho HTTP de autorização às solicitações do webhook. Esse cabeçalho tem o formato: "authorization: Basic <base 64 encoding of the string username:password>".
Cabeçalhos de autenticação Para configurações de webhook, é possível especificar pares de chave-valor opcionais do cabeçalho HTTP. Se fornecido, o Dialogflow adicionará esses cabeçalhos HTTP às solicitações do webhook. É comum fornecer um único par com uma chave de authorization. Os valores do cabeçalho são compatíveis com as referências de parâmetros de sessão e a análise da função do sistema, como nas mensagens de resposta estática.
Autenticação integrada do Cloud Functions É possível usar a autenticação integrada ao Cloud Functions. Para usar esse tipo de autenticação, não forneça nomes de usuário, senhas de login ou cabeçalhos de autorização. Se você fornecer algum desses campos, eles serão usados para autenticação em vez da integrada.
Tokens de identidade de serviço É possível usar tokens de identidade de serviço para autenticação. Se você não informar o nome de usuário, a senha de login ou um cabeçalho com a chave authorization, o Dialogflow considerará automaticamente que os tokens de identidade do serviço precisam ser usados e adicionará um cabeçalho HTTP de autorização às solicitações do webhook. Esse cabeçalho tem o formato: "authorization: Bearer <identity token>".
Autenticação TLS mútua Consulte a documentação Autenticação TLS mútua.

Verificação do certificado HTTPS

Por padrão, o Dialogflow usa o armazenamento de confiança padrão do Google para verificar certificados HTTPS. Se você quiser usar certificados não reconhecidos pelo armazenamento de confiança padrão do Google para seu servidor HTTPS, como certificados autoassinados ou certificados raiz personalizados, consulte Certificados de CA personalizados.

Webhooks específicos do ambiente

Se você estiver usando ambientes para isolar os sistemas de produção de sistemas de desenvolvimento (recomendado), configure os webhooks para serem específicos do ambiente. Para cada recurso de webhook definido, forneça configurações de autenticação e URL exclusivos para cada ambiente definido para o agente.

Isso permite desenvolver e testar com segurança as atualizações de código do webhook antes de implantá-las na produção.

Criar ou editar recursos 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. Após a criação, também é possível editar as configurações de recursos do webhook a qualquer momento.

Para criar ou editar um recurso de webhook:

Console

  1. Abra o Console do Dialogflow CX.
  2. Escolha seu projeto do Google Cloud.
  3. Selecione seu agente.
  4. Selecione a guia Gerenciar.
  5. Clique em Webhooks.
  6. Clique em Criar ou em um recurso de webhook na lista para editar.
  7. Insira as configurações padrão dos recursos do webhook ou flexíveis.
  8. Clique em Save.

API

Para criar um recurso de webhook, consulte o método create para o tipo Webhook. Para editar um recurso do webhook (exceto para configurações específicas do ambiente), consulte o método patch ou update para o tipo Webhook.

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

Protocolo V3 V3beta1
REST Recurso de webhook Recurso de webhook
RPC Interface de webhook Interface de webhook
C++ WebhooksClient (em inglês) Indisponível
C# WebhooksClient (em inglês) Indisponível
Go WebhooksClient (em inglês) Indisponível
Java WebhooksClient (em inglês) WebhooksClient (em inglês)
Node.js WebhooksClient (em inglês) WebhooksClient (em inglês)
PHP Indisponível Indisponível
Python WebhooksClient (em inglês) WebhooksClient (em inglês)
Ruby Indisponível Indisponível

Para editar as configurações específicas do ambiente para um webhook, consulte o método patch ou update para o tipo Environment.

Selecione um protocolo e uma versão para a Referência de ambiente:

Protocolo V3 V3beta1
REST Recurso do ambiente Recurso do ambiente
RPC (remote procedure call) Interface do ambiente Interface do ambiente
C++ EnvironmentsClient (em inglês) Indisponível
C# EnvironmentsClient (em inglês) Indisponível
Go EnvironmentsClient (em inglês) Indisponível
Java EnvironmentsClient (em inglês) EnvironmentsClient (em inglês)
Node.js EnvironmentsClient (em inglês) EnvironmentsClient (em inglês)
PHP Indisponível Indisponível
Python EnvironmentsClient (em inglês) EnvironmentsClient (em inglês)
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á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.

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:

  1. 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:
    1. Crie um novo agente para o projeto.
    2. execute o seguinte comando: 
      gcloud beta services identity create --service=dialogflow.googleapis.com --project=agent-project-id
  2. 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.

Como usar webhooks em contêineres e o framework Go ezcx

Se você quiser implementar um webhook em contêiner usando Go, consulte o framework Go ezcx. Esse framework pode simplificar muitas das etapas necessárias ao criar um webhook.

Como usar o diretório de serviços para acesso a redes privadas

O Dialogflow integra-se ao acesso à rede particular do Diretório de serviços para que ele possa se conectar aos destinos do webhook dentro da rede VPC. Isso mantém o tráfego na rede do Google Cloud e aplica o IAM e o VPC Service Controls.

Para configurar um webhook que segmenta uma rede privada:

  1. Siga a configuração de rede particular do Diretório de serviços para configurar sua rede VPC e o endpoint do Diretório de serviços.

  2. 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
    Conceda à conta de agente de serviço do Dialogflow os seguintes papéis do IAM:

    • servicedirectory.viewer do projeto do diretório de serviços
    • servicedirectory.pscAuthorizedService do projeto de rede

  3. Forneça o serviço do diretório de serviços com o URL e informações de autenticação opcionais ao criar o webhook.

    Console

    Captura de tela do webhook do Diretório de serviços.

    API

    Veja o campo serviceDirectory para o tipo Webhook.

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

    Protocolo V3 V3beta1
    REST Recurso de webhook Recurso de webhook
    RPC Interface de webhook Interface de webhook
    C++ WebhooksClient (em inglês) Indisponível
    C# WebhooksClient (em inglês) Indisponível
    Go WebhooksClient (em inglês) Indisponível
    Java WebhooksClient (em inglês) WebhooksClient (em inglês)
    Node.js WebhooksClient (em inglês) WebhooksClient (em inglês)
    PHP Indisponível Indisponível
    Python WebhooksClient (em inglês) WebhooksClient (em inglês)
    Ruby Indisponível Indisponível

Para resolver problemas, configure uma verificação de tempo de atividade particular para verificar se o Diretório de serviços está configurado corretamente.

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). Por exemplo, verifique o email do token de ID como: 

service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com

Amostras e solução de problemas

Consulte o guia de instruções do webhook.

Anterior
Fulfillments
Próxima
Pesquisar