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 a extração de dados do processamento de linguagem natural do 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 pelo Dialogflow CX. Com um webhook flexível, você define os campos de solicitação e resposta.

Também é possível acessar o código de status HTTP da chamada de webhook usando o parâmetro de solicitação $request.webhook_status_code.

Webhooks padrão

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

Solicitação de webhook padrão

Quando um fulfillment com um webhook é chamado, o Dialogflow CX envia uma solicitação de webhook HTTPS POST 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 outras informações. Por exemplo, a integração do gateway telefônico do Dialogflow CX fornece o identificador de chamadas do usuário final.

Para mais detalhes, consulte a documentação de referência de WebhookRequest (V3) ou WebhookRequest (V3Beta1).

Resposta padrão do webhook

Depois que o serviço de webhook recebe uma solicitação, ele precisa enviar uma resposta que atenda a estes requisitos:

• A resposta precisa ocorrer dentro do tempo limite configurado ao criar o recurso de webhook.
• A resposta precisa ter no máximo 64 KiB.

Para mais detalhes, consulte a documentação de referência de WebhookResponse (V3) ou WebhookResponse (V3Beta1).

Configurações padrão de recursos de webhook

A tabela a seguir descreve as configurações de recursos de webhook para webhooks padrão:

X	Item
Nome de exibição	O nome mostrado no console para o webhook.
Tempo limite do webhook	Quando o Dialogflow CX envia uma solicitação HTTP para seu serviço de webhook, essa configuração controla o tempo limite em segundos para cada tentativa de solicitação individual, não para a conversa como um todo. Se uma tentativa expirar ou falhar com um erro temporário, o Dialogflow CX vai tentar novamente uma vez. Essa nova tentativa pode resultar em um tempo total de resposta de até o dobro do valor de tempo limite configurado antes de retornar um erro. Se ocorrer um tempo limite após a nova tentativa, o Dialogflow CX vai invocar um evento webhook.error.timeout. Para mais detalhes, consulte Tentativas automáticas.
Tipo	Defina como Diretório de serviços se você estiver usando o diretório de serviços para acesso à rede privada. Caso contrário, defina como Serviço da Web genérico.
URL do webhook	Informe o endereço de URL do seu serviço de webhook.
Subtipo	Defina como Padrão.
Webhook específico do ambiente	É possível fornecer webhooks específicos do ambiente.
Autenticação	Consulte a seção 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 da solicitação, os parâmetros de URL da solicitação e os campos das mensagens de solicitação e resposta. A solicitação só pode fornecer valores de parâmetro selecionados, e a resposta só pode fornecer valores de substituição de parâmetro. Isso simplifica a interface entre o agente e o webhook, já que raramente é necessário comunicar algo além dos valores de parâmetro de sessão. Ele também simplifica a implementação do webhook porque as mensagens de solicitação e resposta contêm apenas o que você precisa, e é possível 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 enviadas ao seu serviço de webhook.
• Valores de parâmetro de sessão que o Dialogflow CX deve enviar ao serviço de webhook usando o URL.
• Valores de parâmetro de sessão que o Dialogflow CX deve enviar ao serviço de webhook pelo corpo JSON da solicitação se você escolher POST, PUT ou PATCH como o método.

Para enviar valores de parâmetro de sessão usando o URL da solicitação ou o corpo JSON, use referências de parâmetro. Não é necessário fazer o escape de URL da referência do parâmetro nem colocá-la entre aspas. No ambiente de execução, o Dialogflow CX faz o escape de URL do valor de parâmetro conforme necessário. Uma lista ou um valor composto é fornecido como JSON.

Ao usar uma referência de parâmetro no corpo JSON, é necessário colocar a referência entre aspas, independentemente do tipo de parâmetro. Se o parâmetro for um valor escalar numérico, uma lista ou um valor composto, o Dialogflow CX vai remover as aspas ao enviar a solicitação no ambiente de execução para preservar o tipo de dados do parâmetro. Os tipos escalares de string vão continuar entre aspas. Se um escalar numérico, uma lista ou um valor 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, é possível fornecer os valores de parâmetro de sessão fruit e size ao URL de solicitação da seguinte maneira:

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

E ao corpo JSON da solicitação, da seguinte maneira:

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

Resposta do webhook flexível

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

Sua resposta precisa atender às seguintes limitações:

• A resposta precisa ocorrer dentro do tempo limite configurado ao criar o recurso de webhook. Caso contrário, a solicitação vai expirar.
• A resposta precisa ter no máximo 64 KiB.

Para especificar um campo escalar, de lista ou composto, use o seguinte formato:

$.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 de webhook

A tabela a seguir descreve as configurações de recursos para webhooks flexíveis.

X	Item
Nome de exibição	O nome mostrado no console para o webhook.
Tempo limite do webhook	Quando o Dialogflow CX envia uma solicitação HTTP para seu serviço de webhook, essa configuração controla o tempo limite em segundos para cada tentativa de solicitação individual, não para a conversa como um todo. Se uma tentativa expirar ou falhar com um erro temporário, o Dialogflow CX vai tentar novamente uma vez. Essa nova tentativa pode resultar em um tempo total de resposta de até o dobro do valor de tempo limite configurado antes de retornar um erro. Se ocorrer um tempo limite após a nova tentativa, o Dialogflow CX vai invocar um evento webhook.error.timeout. Para mais detalhes, consulte Tentativas automáticas.
Tipo	Defina como Diretório de serviços se você estiver usando o diretório de serviços para acesso à rede privada. Caso contrário, defina como Serviço da Web genérico.
URL do webhook	Informe o endereço de 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 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 de 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	Isso é usado para fazer upload de certificados de CA 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. Acesse a guia Gerenciar, selecione Webhooks e clique em Criar.
2. Em Subtipo, selecione Flexível.
3. Clique em Configurar usando um modelo predefinido.
4. No menu Tipo de integração, selecione Salesforce.
5. No menu 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ê escolher.
   1. Configure manualmente os campos a seguir, se aplicável, com base nos seus parâmetros:
      • URL do webhook
      • Método
      • JSON do corpo da solicitação
      • Configuração de resposta
   2. Os campos obrigatórios do OAuth serão destacados na seção Autenticação.
6. Clique em Salvar.

Requisitos de serviço do webhook

Seu serviço de webhook precisa atender aos seguintes requisitos:

• Processar solicitações HTTPS. O HTTP não é compatível. Se você hospedar seu serviço de webhook no Google Cloud usando uma solução de computação ou computação sem servidor, consulte a documentação sobre como disponibilizar com HTTPS. Para outras opções de hospedagem, consulte Gerar um certificado SSL para seu domínio.
• Verifique se o URL do serviço de webhook está acessível publicamente, a menos que esteja hospedado como um recurso do Cloud Run ou acessado como um webhook do Diretório de serviços.
• Processe 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 privada do Diretório de Serviços, as chamadas de webhook estarão fora do perímetro de serviço e serão bloqueadas quando o VPC Service Controls for ativado. O Diretório de Serviços é compatível com endpoints limitados. Para mais detalhes, consulte Diretório de Serviços.

Autenticação

Proteja seu serviço de webhook para que apenas você ou seu agente de CX do Dialogflow CX possam fazer solicitações. Configure isso ao criar ou editar um recurso de webhook. O Dialogflow CX é compatível com os seguintes mecanismos de autenticação:

X	Item
Cabeçalhos de autenticação	Para as configurações de webhook, é possível especificar pares de chave-valor opcionais de cabeçalho HTTP. Se fornecidos, o Dialogflow CX adiciona esses cabeçalhos HTTP às solicitações de webhook. É comum fornecer um único par com uma chave de authorization. Os valores de 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áticas. Se você usar uma credencial estática para o cabeçalho authorization, recomendamos que você forneça sua credencial usando o Secret Manager.
Autenticação básica com nome de usuário e senha	Para as configurações de webhook, é possível especificar valores opcionais de nome de usuário e senha de login. Se fornecido, o Dialogflow CX adiciona um cabeçalho HTTP de autorização às solicitações de webhook. Esse cabeçalho está no formato: "authorization: Basic <base 64 encoding of the string username:password>". Recomendamos que você forneça seu nome de usuário e senha usando o Secret Manager.
OAuth de terceiros	É possível especificar a configuração do OAuth de terceiros para que o Dialogflow CX troque um token de acesso do sistema OAuth e o adicione ao cabeçalho HTTP de autorização. Somente o fluxo de credenciais do cliente é aceito. Recomendamos que você forneça a chave secreta do cliente usando o Secret Manager.
Tokens de acesso do agente de serviço	Desativado.
Conta de serviço	É possível usar uma conta 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 escolher o token de ID na seção "Autenticação do agente de serviço", que permite usar o token de ID do agente de serviço para autenticação. Isso permite que você acesse os recursos 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 vão prevalecer. A ordem de prioridade é a seguinte: cabeçalhos de autenticação, autenticação básica, OAuth de terceiros, autenticação do agente de serviço.

Observação: não recomendamos o uso de intervalos de IP para autenticar solicitações de webhook. Se você optar por usar o IP de origem da solicitação para ativar a conectividade no perímetro da rede, permita solicitações dos intervalos listados em https://www.gstatic.com/ipranges/goog.json e negue conexões dos intervalos listados em https://www.gstatic.com/ipranges/cloud.json (esses são os endereços do Google que podem ser usados para implantar cargas de trabalho de terceiros). O Dialogflow não pode garantir intervalos de IP para máquinas que enviam solicitações de webhook.

Observação: após 15 de agosto de 2025, os agentes exportados não vão mais conter credenciais de valor bruto para cabeçalhos de autenticação, autenticação básica com nome de usuário e senha ou OAuth de terceiros.

OAuth de terceiros

O Dialogflow CX coleta um token de acesso de um provedor OAuth de terceiros e o adiciona ao cabeçalho HTTP de autorização ao fazer solicitações de webhook.

A tabela a seguir descreve as configurações de recursos para o OAuth de terceiros:

X	Item
ID do cliente	O ID do cliente a ser usado ao solicitar um token OAuth.
Chave secreta do cliente	A chave secreta a ser usada ao solicitar um token OAuth. Recomendamos que você forneça a chave secreta do cliente usando o Secret Manager.
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 do OAuth para receber um token não incluem os cabeçalhos da solicitação personalizados configurados para a solicitação de webhook. É possível transmitir informações personalizadas para o servidor OAuth como parâmetros na string de consulta do URL do endpoint OAuth.

Observação: os tokens OAuth de terceiros são reutilizados para solicitações de webhook usando o mesmo ID do cliente, URL de endpoint e escopos no mesmo agente de CX do Dialogflow, desde que a solicitação seja feita no mesmo servidor do Dialogflow CX e o token não tenha expirado. Para conseguir 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 ajudar a gerenciar o volume de solicitações que seu agente pode enviar ao provedor OAuth de terceiros.

Token de ID do agente de serviço

O Dialogflow CX pode gerar um token de ID usando o agente de serviço do Dialogflow CX. Esse token é adicionado ao cabeçalho HTTP de autorização quando o Dialogflow CX chama um webhook.

Um token de ID pode ser usado para acessar recursos do Cloud Run depois que você conceder o papel de invocador do Cloud Run (roles/run.invoker) à

[e-mail]

Se os recursos do Cloud Run estiverem no mesmo projeto de recurso, não será necessária uma permissão extra do Identity and Access Management (IAM) para chamá-los.

O público-alvo usado para gerar o token de ID é todo o URL do webhook, exceto os parâmetros de consulta. Se você estiver usando o Cloud Run, verifique se esse URL é compatível com os públicos-alvo do Cloud Run.

Por exemplo, se o URL do webhook for:

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

o seguinte URL precisa estar nos 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 a biblioteca de autenticação do Google para Node.js.

Se o webhook estiver hospedado no Cloud Run e for acessado por um balanceador de carga, adicione o URL do balanceador de carga como um público-alvo personalizado ao Cloud Run. Para mais informações sobre públicos-alvo personalizados, consulte Definir públicos-alvo personalizados para serviços.

Conta de serviço

As contas de serviço podem ser usadas para autenticar solicitações de webhook para qualquer API do Google que as aceite.

Crie uma conta de serviço, caso ainda não tenha feito isso.

Como as contas de serviço são principais, elas podem acessar recursos no seu projeto concedendo a elas um papel, assim como qualquer outro principal. O e-mail da conta de serviço é usado para gerar um token de acesso que é enviado no cabeçalho Authorization da solicitação de webhook.

Para configurar o webhook para usar contas de serviço, é necessário ter as seguintes permissões:

• roles/iam.serviceAccountUser

Para gerar tokens, o agente de serviço do Dialogflow precisa ter as seguintes permissões:

• roles/iam.serviceAccountTokenCreator

A conta de serviço também precisa ter permissões para acessar o serviço que hospeda o webhook.

Observação :se você estiver tentando usar contas de serviço em vários projetos, verifique se a política da organização permite isso. As duas permissões precisam ser concedidas no projeto que contém a conta de serviço.

Autenticação do Secret Manager

Se você usa cabeçalhos de autenticação, autenticação básica com nome de usuário e senha ou OAuth de terceiros, é possível armazenar as credenciais como secrets usando o Secret Manager. Veja a seguir as etapas necessárias para autenticar seu webhook usando secrets:

1. Crie um secret se ainda não tiver um.
2. Conceda ao agente de serviço do Dialogflow o papel de acessador de secrets do Secret Manager (roles/secretmanager.secretAccessor) no novo secret.
3. Copie a credencial para a área de transferência.
4. Adicione uma nova versão do secret ao seu secret e cole sua credencial como o valor do secret:
   • Se você usa cabeçalhos de autenticação, digite Bearer <YOUR_CREDENTIAL>.
   • Se você usa a autenticação básica de nome de usuário e senha, digite <YOUR_USERNAME>:<YOUR_PASSWORD>.
   • Omita qualquer caractere de nova linha no final.
5. Copie o nome da versão do secret que você adicionou. O formato do nome é projects/<var>PROJECT_ID</var>/secrets/<var>SECRET_ID</var>/versions/<var>VERSION_ID</var>.
6. Abra a tela de edição do webhook.
7. Defina as configurações de autenticação:
   • Se você usa cabeçalhos de autenticação, crie um novo cabeçalho da solicitação de versão do secret. Insira "Authorization" no campo Chave e cole o nome da versão do secret no campo Versão do secret.
   • Para autenticação básica com nome de usuário e senha, clique em Versão do secret em Autenticação básica e cole o nome da versão do secret no campo Versão do secret.
   • Se você usar o OAuth de terceiros, clique em Versão do secret em OAuth de terceiros e cole o nome da versão do secret no campo Versão do secret.
8. Clique em Salvar.

Observação :só aceitamos secrets globais do Secret Manager. Não oferecemos suporte a secrets regionais.

Verificação do certificado HTTPS

Por padrão, o Dialogflow CX usa o repositório de confiança padrão do Google para verificar certificados HTTPS. Se você pretende usar certificados não reconhecidos pelo repositório 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ê usa ambientes para isolar a produção do desenvolvimento, é possível configurar os webhooks para serem específicos do ambiente. É possível fornecer configurações de URL e autenticação específicas do ambiente para cada recurso de webhook.

Essa configuração permite que você desenvolva e teste 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 executar um serviço de webhook, crie um recurso de webhook no seu agente que inclua informações de conectividade e autenticação. É 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. Acesse seu projeto.
3. Selecione seu agente.
4. Clique na guia Gerenciar.
5. Clique em Webhooks.
6. Clique em Criar ou selecione um webhook para editar.
7. Defina as configurações de recursos de webhook padrão ou as configurações de recursos de webhook flexíveis.
8. Clique em Salvar.

API

Para saber como criar um recurso de webhook, consulte o método create para o tipo Webhook. Para informações sobre como 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 de webhook	Recurso de 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 saber como 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 de 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, o código do webhook precisará 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 do servidor
• 503: serviço indisponível

O Dialogflow CX invoca um erro de webhook ou um evento integrado de tempo limite e continua o processamento normalmente nas seguintes situações de erro:

• O tempo limite de resposta foi excedido.
• Um código de status de erro é recebido.
• A resposta é inválida.
• O serviço de webhook está indisponível.

Se a chamada de serviço do webhook foi acionada por uma chamada de API de intent de detecção, o campo queryResult.webhookStatuses na resposta de intent de detecção contém as informações de status do webhook.

Novas tentativas automáticas

O Dialogflow CX tenta novamente as solicitações em determinados erros de webhook para melhorar a robustez. As novas tentativas automáticas são ativadas por padrão e não podem ser desativadas.

O Dialogflow CX executa uma única nova tentativa para falhas temporárias, como tempos limite de solicitação, conexões de rede interrompidas e códigos de status HTTP no intervalo 5xx (como 500 Server fault ou 503 Service unavailable). Erros de cliente de terminal, como o código de status HTTP 404 Not found, falham imediatamente sem uma nova tentativa.

Latência cumulativa e orçamento de tempo limite

Como o Dialogflow CX tenta novamente as falhas temporárias uma vez, um endpoint de webhook que não responde pode resultar em um tempo de resposta cumulativo de até o dobro do valor de tempo limite configurado antes que o Dialogflow CX retorne um erro. Por exemplo, com a configuração padrão de tempo limite de 5 segundos, um endpoint que não responde expira após 5 segundos na tentativa inicial e após mais 5 segundos na nova tentativa. Isso resulta em uma latência total de aproximadamente 10 segundos antes que o Dialogflow CX invoque manipuladores de erros, como um manipulador de eventos webhook.error.timeout ou sys.no-match-default.

Se a arquitetura tiver limites rígidos de latência upstream (como sistemas de telefonia ou resposta interativa por voz (IVR) que encerram chamadas após um tempo limite de 10 segundos), planeje as duas tentativas definindo o tempo limite do webhook como metade da janela permitida (por exemplo, entre 2,5 e 4 segundos).

Práticas recomendadas para novas tentativas

Para lidar com novas tentativas de maneira eficaz no serviço de webhook:

• Implemente a idempotência ou a eliminação de duplicação de solicitações na lógica do serviço de webhook para processar solicitações duplicadas com segurança.
• Se a operação do webhook demorar mais do que o tempo limite configurado, retorne uma resposta imediata com o código de status HTTP 200 OK e uma mensagem de fallback, além de processar a tarefa de longa duração de forma assíncrona.

Usando o Cloud Run

Atenção: nesta seção, descrevemos como usar recursos seguros do Cloud Run para webhooks do Dialogflow CX. Recomendamos que você proteja seus recursos. Se você optar por autenticar com nome de usuário e senha baseados em URL ou cabeçalhos HTTP, será necessário permitir o acesso não autenticado ao recurso do Cloud Run.

O Dialogflow CX se integra ao Cloud Run para que você possa criar um webhook seguro e sem servidor. Se você criar um recurso do Cloud Run que resida no mesmo projeto que o agente, selecione Autenticação do agente de serviço e, em seguida, selecione Token de ID na configuração de autenticação para que o agente possa chamar o webhook com segurança.

É necessário configurar manualmente essa integração nas duas situações a seguir:

1. A conta de serviço do agente de serviço do Dialogflow CX com o seguinte endereço precisa existir para o projeto do agente:

   [e-mail]

   Essa conta de serviço especial e a chave associada normalmente são criadas automaticamente quando você cria o primeiro agente para um projeto. Se o agente foi criado antes de 1º de novembro de 2020, é possível acionar a criação dessa 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 de webhook estiver em um projeto diferente do agente, você precisará fornecer o papel do IAM de Invocador do Cloud Run ou Invocador do Cloud Functions à conta de serviço do Agente de serviço do Dialogflow CX no projeto de recurso do Cloud Run.

Em seguida, selecione Autenticação do agente de serviço > Token de ID na seção Configuração de autenticação.

Como usar webhooks conteinerizados e o framework ezcx do Go

Para implementar um webhook conteinerizado usando Go, consulte o framework ezcx do Go. Esse framework simplifica muitas das etapas necessárias para criar um webhook.

Como usar o Cloud Run com tráfego somente interno

Observação: não é possível usar o Cloud Run fora do perímetro do VPC Service Controls do projeto do agente de CX do Dialogflow CX para webhooks.

É possível usar recursos do Cloud Run configurados para aceitar tráfego interno de redes de nuvem privada virtual (VPC) no mesmo projeto ou no mesmo perímetro do VPC Service Controls como um webhook, desde que o agente esteja no mesmo projeto ou no mesmo perímetro do VPC Service Controls.

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

O Dialogflow CX se integra ao acesso à rede privada do Diretório de Serviços para se conectar a destinos de webhook na sua 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 as instruções em Configuração de rede privada do Diretório de Serviços para configurar sua rede VPC e o endpoint do Diretório de Serviços.

   Observação: o Dialogflow CX armazena em cache as informações do Diretório de Serviços por 90 segundos. Isso significa que, quando você atualiza o endpoint do Diretório de Serviços, a alteração leva 90 segundos para ocorrer.

2. A conta de serviço do agente de serviço do Dialogflow CX com o seguinte endereço precisa existir para o projeto do agente:

   [e-mail]

   Conceda os seguintes papéis à conta de serviço do agente de serviço do Dialogflow CX no projeto em que o Diretório de Serviços está localizado:

   • servicedirectory.viewer
   • servicedirectory.pscAuthorizedService

   Além disso, se o Diretório de serviços estiver em um projeto diferente do agente de CX do Dialogflow, você também precisará conceder o papel servicedirectory.viewer à conta do agente de serviço do Dialogflow CX no projeto que hospeda o agente de CX do Dialogflow.

3. Especifique o serviço do Diretório de Serviços, o URL e as 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 de 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

Para mais informações, consulte o guia de instruções do webhook.