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 usar os dados extraídos pelo processamento de linguagem natural dos agentes de conversação (Dialogflow CX) para gerar respostas dinâmicas, validar os dados coletados ou acionar 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 por agentes de conversação (Dialogflow CX). Com um webhook flexível, você define os campos de solicitação e resposta.

Webhooks padrão

Com webhooks padrão, você usa mensagens de solicitação e resposta definidas por agentes de conversação (Dialogflow CX). A mensagem de solicitação fornece muitos detalhes sobre a sessão. Por exemplo, página ativa atual, intent com correspondência recente valores de parâmetros de sessão e respostas definidas pelo agente estão incluídos.

Solicitação de webhook padrão

Quando um fulfillment com um webhook é chamado, Os agentes de conversação (Dialogflow CX) enviam uma solicitação de webhook POST HTTPS para seu serviço de webhook. O corpo dessa solicitação é um objeto JSON WebhookRequest com informações sobre a sessão.

Algumas integrações preenchem o campo WebhookRequest.payload com informações adicionais. Por exemplo, o Integração do Dialogflow CX Phone Gateway 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 padrão 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(V3) ou WebhookResponse(V3Beta1) para mais detalhes.

Configurações padrão do recurso de webhook

Confira a seguir as configurações de recursos de webhooks padrão:

Termo	Definição
Nome de exibição	O nome mostrado no console para o webhook.
Tempo limite do webhook	Quando os agentes de conversação (Dialogflow CX) enviam uma solicitação de webhook para o serviço de webhook, o tempo limite pode ser atingido enquanto aguarda uma resposta. Essa configuração controla o tempo limite em segundos. Se ocorrer um tempo limite, os agentes de conversação (Dialogflow CX) vão invocar um evento webhook.error.timeout.
Tipo	Defina como Diretório de serviços se estiver usando o diretório de serviços para acesso à rede particular. Caso contrário, defina como Serviço da Web genérico.
URL do webhook	Informe o endereço do URL do serviço de webhook.
Subtipo	Definido como Padrão
Webhook específico do ambiente	É possível fornecer webhooks específicos do ambiente.
Autenticação	Consulte a seção de autenticação.
Certificado de CA personalizado	Ele é usado para fazer upload de certificados de AC personalizados.

Webhooks flexíveis

Com webhooks flexíveis, você define o método HTTP de solicitação, os parâmetros do URL de solicitação e os campos das mensagens de solicitação e resposta. A solicitação só pode fornecer valores de parâmetros selecionados, e a resposta só pode fornecer valores de substituição de parâmetro. Essa limitação é benéfica, porque simplifica a interface entre o agente e o webhook. Raramente há a necessidade de comunicar algo além de parâmetros de sessão entre um agente e um webhook. Isso também simplifica a implementação do webhook, porque as mensagens de solicitação e resposta contêm apenas o que você precisa, e fornecer mensagens de webhook únicas 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 enviados ao serviço de webhook.
• Valores de parâmetro de sessão que os agentes de conversa (Dialogflow CX) precisam enviar ao seu serviço de webhook usando o URL.
• Se você escolher POST, PUT ou PATCH como o método, é possível especificar valores de parâmetro de sessão que os agentes de conversação (Dialogflow CX) precisam enviar para o serviço de webhook pelo corpo JSON da solicitação.

Para enviar valores de parâmetro de sessão usando o URL de solicitação ou o corpo JSON, use referências de parâmetros como você faria normalmente. Não é necessário fazer o escape do URL da referência de parâmetro. e você não colocar a referência entre aspas. No momento da execução, os agentes de conversação (Dialogflow CX) vão escapar o valor do parâmetro no URL conforme necessário. Uma lista ou um valor composto será fornecido como JSON.

Ao usar uma referência de parâmetro no corpo JSON, você deve colocar a referência entre aspas, seja qual for o tipo de parâmetro. Se o parâmetro for um valor numérico escalar, de lista ou composto, os agentes de conversação (Dialogflow CX) vão 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 vão continuar entre aspas. Se um valor escalar, lista ou composto numérico 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: é possível fornecer os valores de parâmetro de sessão fruit e size. ao URL de solicitação, da seguinte forma:

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

E, para o corpo JSON da solicitação, como este:

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

Resposta flexível do webhook

Ao criar o recurso de webhook para seu agente, é possível especificar parâmetros de sessão que os agentes de conversação (Dialogflow CX) precisam definir a 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

Confira a seguir as configurações de recursos de webhooks flexíveis:

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

Usar um modelo personalizado predefinido

O Dialogflow oferece modelos personalizados predefinidos que podem ser usados para integrar webhooks flexíveis ao CRM do Salesforce.

1. Na guia Manage, clique em Webhooks e em + Create.

2. Em Subtipo, selecione Flexível.

3. Clique em Configurar usando um modelo predefinido para ativar o recurso.

4. No menu suspenso Tipo de integração, selecione Salesforce.

5. No menu suspenso Nome da API, selecione um nome de API. O modelo preenche automaticamente o formulário de webhook com base no nome da API que você que você escolher.

   1. É possível configurar manualmente os campos a seguir, se aplicável, com base nos parâmetros:

      • URL do webhook
      • Método
      • Corpo da solicitação JSON
      • Configuração da resposta

   2. Os campos obrigatórios do OAuth serão destacados na seção Autenticação.

6. Clique em Salvar para criar o webhook.

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.
• O URL das solicitações precisa ser acessível publicamente, a menos que seja hospedado como uma função do Cloud Run ou acessado como um webhook do diretório de serviços.
• Ele precisa processar solicitações e respostas, conforme descrito na seção webhook padrão ou webhook flexível.
• Se o agente não se integrar ao acesso à rede particular do Diretório de serviços, as chamadas do webhook serão consideradas fora do perímetro de serviço e bloqueadas ao ativar o VPC Service Controls. Endpoints limitados são compatíveis com o Diretório de serviços. Consulte Diretório de serviços para detalhes.

Autenticação

Observação: os IPs de origem do webhook estão no subconjunto dos listados em https://www.gstatic.com/ipranges/goog.json, que exclui os de https://www.gstatic.com/ipranges/cloud.json. Além disso, o Dialogflow não oferece nenhuma garantia sobre intervalos de IP para máquinas que enviam solicitações de webhook. Em vez de restringir o acesso usando um intervalo de IP, você deve usar um dos métodos de autenticação listados na tabela abaixo.

É importante proteger seu serviço de webhook para que somente você ou seus agentes de conversação (Dialogflow CX) sejam autorizados a fazer solicitações. Isso é configurado ao criar um recurso de webhook. Os agentes de conversação (Dialogflow CX) são compatíveis com os seguintes mecanismos de autenticação:

Termo	Definição
Cabeçalhos de autenticação	Nas configurações do webhook, especifique pares de chave-valor do cabeçalho HTTP opcionais. Se fornecidos, os agentes de conversação (Dialogflow CX) adicionam esses cabeçalhos HTTP às solicitações de webhook. É comum fornecer um único par com uma chave de authorization. Os valores do cabeçalho são compatíveis com referências de parâmetros de sessão e análise de funções do sistema como em mensagens de resposta estática.
Autenticação básica com nome de usuário e senha	Para as configurações do webhook, você pode especificar valores opcionais de nome de usuário e senha de login. Se fornecido, os Agentes de conversa (Dialogflow CX) adicionam um cabeçalho HTTP de autorização às solicitações de webhook. Esse cabeçalho tem o formato: "authorization: Basic <base 64 encoding of the string username:password>".
OAuth de terceiros	É possível especificar a configuração do OAuth de terceiros para que os agentes de conversação (Dialogflow CX) troquem um token de acesso do sistema OAuth e o adicionem ao cabeçalho HTTP de autorização. Somente o fluxo de credenciais do cliente é aceito.
Tokens de acesso do agente de serviço	Você pode selecionar o token de acesso na autenticação do agente de serviço para usar tokens de acesso do agente de serviço para autenticação. Isso pode ser usado para acessar outras APIs do Google Cloud.
Tokens de ID do agente de serviço	É possível selecionar o token de ID na autenticação do agente de serviço para usar tokens de ID do agente de serviço para autenticação. Isso pode ser usado para acessar as funções e os serviços do Cloud Run.
Autenticação TLS mútua	Consulte a documentação sobre Autenticação TLS mútua.

Observação: se várias opções de autenticação estiverem ativadas, as opções de prioridade mais alta terão precedência. Ordem de prioridade das opções de autenticação: Cabeçalhos de autenticação, Autenticação básica, OAuth de terceiros, Autenticação de agente de serviço.

OAuth de terceiros

Os agentes de conversação (Dialogflow CX) podem coletar um token de acesso de um provedor OAuth de terceiros e adicioná-lo ao cabeçalho HTTP de autorização ao fazer as solicitações de webhook.

Confira a seguir as configurações de recursos para OAuth de terceiros:

Termo	Definição
ID do cliente	O ID do cliente a ser usado para solicitar um token OAuth.
Chave secreta do cliente	O segredo a ser usado ao solicitar um token OAuth.
URL do endpoint OAuth	O URL a ser usado para solicitar um token OAuth.
Escopos do OAuth	Uma lista separada por vírgulas de escopos em que o token OAuth pode ser usado.

As solicitações enviadas ao URL do endpoint OAuth para receber um token não incluem os cabeçalhos de solicitação personalizados configurados para a solicitação de webhook. É possível transmitir informações personalizadas ao servidor OAuth como parâmetros na string de consulta do URL do endpoint OAuth.

Observação: tokens OAuth de terceiros são reutilizados para solicitações de webhook usando o mesmo ID do cliente, URL do endpoint e escopos no mesmo agente do Dialogflow CX, desde que a solicitação seja feita no mesmo servidor do Dialogflow CX e o token não tenha expirado. Para alcançar alta disponibilidade, os agentes são implantados em vários servidores individuais que não compartilham caches de token OAuth. Ao implantar uma solução que usa tokens OAuth de terceiros, considere cuidadosamente implementar um proxy de API para gerenciar o volume de solicitações que o agente pode enviar ao provedor OAuth de terceiros.

Tokens de acesso do agente de serviço

Os agentes de conversação (Dialogflow CX) podem gerar um token de ID ou token de acesso usando o agente de serviço de agentes de conversação (Dialogflow CX).

O token é adicionado ao cabeçalho HTTP de autorização quando os agentes de conversação (Dialogflow CX) chamam um webhook.

Token de ID

Um token de ID pode ser usado para acessar as funções do Cloud Run e os serviços do Cloud Run depois que você concede o papel invocador para

[e-mail]

Se as funções e os serviços do Cloud Run estiverem no mesmo projeto de recursos, não será necessário ter uma permissão adicional do IAM para invocá-los.

O público-alvo usado para gerar o token de ID será o URL inteiro do webhook, exceto os parâmetros de consulta. Se você estiver usando o Cloud Run, verifique se os públicos-alvo do Cloud Run oferecem suporte a esse URL. Por exemplo, se o URL do webhook for

https://myproject.cloudfunctions.net/my-function/method1?query=value

o URL a seguir precisa estar em públicos-alvo personalizados.

https://myproject.cloudfunctions.net/my-function/method1

Qualquer webhook também pode validar o token usando bibliotecas de cliente do Google ou bibliotecas de código aberto, como github.com/googleapis/google-auth-library-nodejs.

Token de acesso

Um token de acesso pode ser usado para acessar outras APIs do Google Cloud depois que você concede os papéis necessários para

[e-mail]

Verificação do certificado HTTPS

Por padrão, os agentes de conversação (Dialogflow CX) usam o repositório de confiança padrão do Google para verificar o HTTPS certificados. 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 sistemas de produção de sistemas de desenvolvimento (recomendado), configure os webhooks para serem específicos do ambiente. Para cada recurso do webhook definido, você pode fornecer 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 do código do webhook antes de implantá-los na produção.

Criar ou editar recursos do 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. Depois da criação, você também pode editar as configurações do recurso de 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 do recurso de webhook padrão ou do recurso de webhook flexível.
8. Clique em Salvar.

API

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

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

Protocolo	V3	V3beta1
REST	Recurso webhook	Recurso webhook
RPC	Interface do webhook	Interface do webhook
C++	WebhooksClient	Indisponível
C#	WebhooksClient	Indisponível
Go	WebhooksClient	Indisponível
Java	WebhooksClient	WebhooksClient
Node.js	WebhooksClient	WebhooksClient
PHP	Indisponível	Indisponível
Python	WebhooksClient	WebhooksClient
Ruby	Indisponível	Indisponível

Fechar

Para editar as configurações específicas do ambiente de um webhook, consulte o método patch ou update para o tipo Environment. Acesse a referência da API Environment

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

Protocolo	V3	V3beta1
REST	Recurso do ambiente	Recurso de ambiente
RPC (remote procedure call)	Interface do ambiente	Interface do ambiente
C++	EnvironmentsClient	Indisponível
C#	EnvironmentsClient	Indisponível
Go	EnvironmentsClient	Indisponível
Java	EnvironmentsClient	EnvironmentsClient
Node.js	EnvironmentsClient	EnvironmentsClient
PHP	Indisponível	Indisponível
Python	EnvironmentsClient	EnvironmentsClient
Ruby	Indisponível	Indisponível

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 seguintes situações de erro, Os agentes de conversação (Dialogflow CX) invocam um erro de webhook ou um tempo limite evento integrado e continua o processamento 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.

Novas tentativas automáticas

Os agentes de conversação (Dialogflow CX) incluem mecanismos internos que tentam novamente automaticamente em determinados erros de webhook para melhorar a robustez. Somente erros não terminais são retentativas (por exemplo, erros de tempo limite ou de conexão).

Para reduzir a probabilidade de chamadas duplicadas:

• Definir limites maiores de tempo limite do webhook.
• Suporte à idempotência na lógica do webhook ou à eliminação de duplicação.

Como usar as funções do Cloud Run

Observação: esta seção descreve como usar funções seguras do Cloud Run para webhooks de agentes de conversação (Dialogflow CX). É recomendável manter suas funções seguras. No entanto, se você escolher autenticar com nome de usuário e senha baseados em URL ou cabeçalhos HTTP, permita o acesso não autenticado à sua função.

Os agentes de conversação (Dialogflow CX) se integram às funções do Cloud Run, para que você crie facilmente um webhook seguro e sem servidor. Se você criar uma função que reside no mesmo projeto que seu agente, basta selecionar Service Agent Auth -> Token de ID na configuração do Auth, o agente poderá chamar o webhook com segurança.

No entanto, há duas situações em que é preciso configurar essa integração manualmente:

1. O agente de serviço dos agentes de conversa (Dialogflow CX) conta de serviço com o seguinte endereço deve existir para seu projeto de agente:

   [e-mail]

   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 1o de novembro de 2020, talvez você acione a criação desta conta de serviço especial:
   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 estiver em um projeto diferente do agente, é preciso informar o Chamador do Cloud Functions Papel do IAM à conta de serviço do Agente de serviço dos agentes de conversação (Dialogflow CX) no projeto da sua função.
3. Selecione Autentificação do agente de serviço -> Token de ID na seção "Configuração de autenticação".

Como usar webhooks conteinerizados e o framework do Go ezcx

Se você quiser implementar um webhook conteinerizado usando Go, consulte o Framework do Go ezcx. Esse framework pode simplificar muitas das etapas necessárias para criar um webhook.

Como usar as funções do Cloud Run com tráfego somente interno

Observação :use as funções do Cloud Run fora do perímetro do VPC Service Controls O projeto de agente do Dialogflow CX para webhooks não é compatível.

As funções do Cloud Run configuradas para aceitar tráfego interno de redes VPC no mesmo projeto ou no mesmo perímetro VPC SC podem ser usadas como um webhook, desde que o agente esteja no mesmo projeto ou no mesmo perímetro VPC SC.

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

Os agentes de conversação (Dialogflow CX) se integram 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.

   Observação: os agentes de conversação (Dialogflow CX) armazenam em cache as informações do diretório de serviços por 90 segundos. Ou seja, se você atualizar o endpoint do Diretório de serviços, a alteração levará 90 segundos. Além disso, se você estiver configurando vários endpoints para redundância, os agentes de conversação (Dialogflow CX) poderão enviar tráfego por um endpoint com falha por 90 segundos.

2. O agente de serviço dos agentes de conversa (Dialogflow CX) conta de serviço com o seguinte endereço deve existir para seu projeto de agente:

   [e-mail]

   Conceda à conta de serviço do Agente de serviço dos agentes de conversação (Dialogflow CX) 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

   

   API

   Veja o campo serviceDirectory para o tipo Webhook. Acesse a referência da API Webhook

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

   Protocolo	V3	V3beta1
   REST	Recurso de webhook	Recurso webhook
   RPC	Interface do webhook	Interface do webhook
   C++	WebhooksClient	Indisponível
   C#	WebhooksClient	Indisponível
   Go	WebhooksClient	Indisponível
   Java	WebhooksClient	WebhooksClient
   Node.js	WebhooksClient	WebhooksClient
   PHP	Indisponível	Indisponível
   Python	WebhooksClient	WebhooksClient
   Ruby	Indisponível	Indisponível

   Fechar

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

Amostras e solução de problemas

Consulte o guia de instruções do webhook.