Webhooks

Os Webhooks são serviços que alojam a lógica da sua empresa ou chamam outros serviços. Durante uma sessão, os webhooks permitem-lhe usar os dados extraídos pelo processamento de linguagem natural dos agentes conversacionais (Dialogflow CX) para gerar respostas dinâmicas, validar dados recolhidos ou acionar ações no back-end.

Um webhook pode ser um webhook padrão ou um webhook flexível. Com um webhook padrão, os campos de pedido e resposta são definidos por agentes conversacionais (Dialogflow CX). Com um webhook flexível, define os campos de pedido e resposta.

Webhooks padrão

Com webhooks padrão, usa mensagens de pedido e resposta definidas por agentes conversacionais (Dialogflow CX). A mensagem de pedido fornece muitos detalhes sobre a sessão. Por exemplo, a página ativa atual, a intenção correspondente recente, os valores dos parâmetros da sessão e as respostas definidas pelo agente estão todos incluídos.

Pedido de webhook padrão

Quando um preenchimento com um webhook é chamado, os agentes conversacionais (Dialogflow CX) enviam um pedido de webhook HTTPS POST para o seu serviço de webhook. O corpo deste pedido é um WebhookRequestobjeto JSON com informações sobre a sessão.

Algumas integrações preenchem o campo WebhookRequest.payload com informações adicionais. Por exemplo, a integração do Dialogflow CX Phone Gateway fornece o identificador de chamadas do utilizador final.

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

Resposta padrão do webhook

Assim que o seu serviço de webhook recebe um pedido de webhook, tem de enviar uma resposta de webhook. As seguintes limitações aplicam-se à sua resposta:

• A resposta tem de ocorrer dentro de um limite de tempo configurado por si quando cria o recurso webhook, caso contrário, o pedido vai exceder o limite de tempo.
• A resposta tem de ter um tamanho inferior ou igual a 64 KiB.

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

Definições de recursos de webhook padrão

A secção seguinte descreve as definições de recursos de webhooks para webhooks padrão:

Vigência	Definição
Nome a apresentar	O nome apresentado na consola para o webhook.
Limite de tempo do webhook	Quando os agentes conversacionais (Dialogflow CX) enviam um pedido de webhook para o seu serviço de webhook, pode ocorrer um limite de tempo enquanto aguardam uma resposta. Esta definição controla esse limite de tempo em segundos. Se ocorrer um limite de tempo, os agentes conversacionais (Dialogflow CX) invocam um evento webhook.error.timeout.
Tipo	Defina como Diretório de serviços se estiver a usar o diretório de serviços para acesso à rede privada. Caso contrário, defina como Serviço Web genérico.
URL do webhook	Indique o endereço URL do seu serviço de webhook.
Subtipo	Definido como Padrão
Webhook específico do ambiente	Pode fornecer webhooks específicos do ambiente.
Autenticação	Consulte a secção de autenticação.
Certificado da AC personalizado	Isto é usado para carregar certificados de AC personalizados.

Webhooks flexíveis

Com os webhooks flexíveis, define o método HTTP do pedido, os parâmetros de URL do pedido e os campos das mensagens de pedido e resposta. O pedido só pode fornecer valores de parâmetros selecionados e a resposta só pode fornecer valores de substituição de parâmetros. Esta limitação é, na verdade, benéfica, uma vez que simplifica a interface entre o agente e o webhook. Raramente é necessário comunicar algo que não sejam os valores dos parâmetros de sessão entre um agente e um webhook. Também simplifica a implementação do webhook, porque as mensagens de pedido e resposta contêm apenas o que precisa, e pode fornecer mensagens de webhook únicas para vários cenários.

Pedido de webhook flexível

Quando criar o recurso de webhook para o seu agente, pode especificar o seguinte para pedidos de webhook:

• O método HTTP usado para pedidos de webhook enviados para o seu serviço de webhook.
• Valores dos parâmetros de sessão que os agentes conversacionais (Dialogflow CX) devem enviar para o seu serviço de webhook através do URL.
• Se escolher POST, PUT ou PATCH como método, pode especificar valores de parâmetros de sessão que os agentes conversacionais (Dialogflow CX) devem enviar para o seu serviço de webhook através do corpo JSON do pedido.

Para enviar valores de parâmetros de sessão através do URL de pedido ou do corpo JSON, use referências de parâmetros como faria normalmente. Não precisa de aplicar a carateres de escape de URL à referência do parâmetro, nem colocar a referência entre aspas. Em tempo de execução, os agentes conversacionais (Dialogflow CX) escapam o valor do parâmetro do URL conforme necessário. É fornecida uma lista ou um valor composto como JSON.

Quando usar uma referência de parâmetro no corpo JSON, tem de incluir a referência entre aspas, independentemente do tipo de parâmetro. Se o parâmetro for realmente um valor numérico escalar, de lista ou composto, os agentes conversacionais (Dialogflow CX) removem as aspas quando enviam o pedido no tempo de execução para preservar o tipo de dados do parâmetro. Os tipos escalares de string vão permanecer entre aspas. Se for feita referência a um valor escalar, de lista ou composto numérico num valor de string (por exemplo: "Este é um número: $session.params.size"), o parâmetro é tratado como uma string ("Este é um número: 3").

Por exemplo, pode fornecer os valores dos parâmetros de sessão fruit e size ao URL do pedido da seguinte forma:

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

E, ao corpo JSON do pedido, da seguinte forma:

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

Resposta flexível do webhook

Quando cria o recurso de webhook para o seu agente, pode especificar parâmetros de sessão que os agentes conversacionais (Dialogflow CX) devem definir para campos específicos da resposta do webhook em tempo de execução.

As seguintes limitações aplicam-se à sua resposta:

• A resposta tem de ocorrer dentro de um limite de tempo configurado por si quando cria o recurso webhook, caso contrário, o pedido vai exceder o limite de tempo.
• A resposta tem de ter um tamanho inferior 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" (valor), use o seguinte:

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

Definições de recursos de webhook flexíveis

A secção seguinte descreve as definições de recursos de webhooks para webhooks flexíveis:

Vigência	Definição
Nome a apresentar	O nome apresentado na consola para o webhook.
Limite de tempo do webhook	Quando os agentes conversacionais (Dialogflow CX) enviam um pedido de webhook para o seu serviço de webhook, pode ocorrer um limite de tempo enquanto aguardam uma resposta. Esta definição controla esse limite de tempo em segundos. Se ocorrer um limite de tempo, os agentes conversacionais (Dialogflow CX) invocam um evento webhook.error.timeout.
Tipo	Defina como Diretório de serviços se estiver a usar o diretório de serviços para acesso à rede privada. Caso contrário, defina como Serviço Web genérico.
URL do webhook	Indique o endereço URL do seu serviço de webhook, que pode incluir referências a parâmetros de sessão.
Subtipo	Definido como Flexível
Método	Defina o método HTTP para o pedido de webhook.
Corpo do pedido	Indique o corpo JSON do pedido conforme descrito acima.
Configuração da resposta	Indique os parâmetros de sessão que devem ser definidos para os campos de resposta conforme descrito acima.
Webhook específico do ambiente	Pode fornecer webhooks específicos do ambiente.
Autenticação	Consulte a secção de autenticação.
Certificado da AC personalizado	Isto é usado para carregar certificados de AC personalizados.

Use um modelo personalizado predefinido

O Dialogflow oferece modelos personalizados predefinidos que pode usar para integrar webhooks flexíveis com o CRM Salesforce.

1. No separador Gerir, clique em Webhooks e, de seguida, em + Criar.

2. Em Subtipo, selecione Flexível.

3. Clique em Configurar com modelo predefinido para ativar a funcionalidade.

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

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

   1. Pode configurar manualmente os seguintes campos, se aplicável, com base nos seus parâmetros:

      • URL do webhook
      • Método
      • JSON do corpo do pedido
      • Configuração da resposta

   2. Os campos OAuth obrigatórios são realçados na secção Autenticação.

6. Clique em Guardar para criar o webhook.

Requisitos do serviço de webhook

O seu serviço de webhook tem de cumprir os seguintes requisitos:

• Tem de processar pedidos HTTPS. O HTTP não é suportado. Se alojar o seu serviço de webhook na Google Cloud Platform através de uma solução de computação ou sem servidor, consulte a documentação do produto para a publicação com HTTPS. Para outras opções de alojamento, consulte o artigo Obtenha um certificado SSL para o seu domínio.
• O respetivo URL para pedidos tem de ser acessível publicamente, exceto se estiver alojado como um recurso do Cloud Run ou se lhe aceder como um webhook do diretório de serviços.
• Tem de processar pedidos e respostas, conforme descrito na secção webhook padrão ou webhook flexível.
• Se o seu agente não se integrar com o acesso à rede privada do Service Directory, as chamadas de webhook são consideradas fora do perímetro de serviço e são bloqueadas quando ativa os VPC Service Controls. Os pontos finais limitados são suportados pelo diretório de serviços. Consulte o diretório de serviços para ver detalhes.

Autenticação

É importante proteger o seu serviço de webhook, para que apenas o utilizador ou o seu agente de agentes conversacionais (Dialogflow CX) estejam autorizados a fazer pedidos. Esta opção é configurada quando cria ou edita um recurso de webhook. Os agentes conversacionais (Dialogflow CX) suportam os seguintes mecanismos de autenticação:

Vigência	Definição
Cabeçalhos de autenticação	Para as definições de webhook, pode especificar pares de chave-valor de cabeçalho HTTP opcionais. Se forem fornecidos, os agentes conversacionais (Dialogflow CX) adicionam estes cabeçalhos HTTP aos pedidos de webhook. É comum fornecer um único par com uma chave de authorization. Os valores dos cabeçalhos suportam referências de parâmetros de sessão e análise de funções do sistema, tal como nas mensagens de resposta estáticas. Se usar uma credencial estática para o cabeçalho authorization, recomendamos que forneça a sua credencial através do Secret Manager.
Autenticação básica com nome de utilizador e palavra-passe	Para as definições de webhook, pode especificar valores de nome de utilizador e palavra-passe de início de sessão opcionais. Se fornecidos, os agentes conversacionais (Dialogflow CX) adicionam um cabeçalho HTTP de autorização aos pedidos de webhook. Este cabeçalho tem o seguinte formato: "authorization: Basic <base 64 encoding of the string username:password>". Recomendamos que forneça o seu nome de utilizador e palavra-passe através do Secret Manager.
OAuth de terceiros	Pode especificar a configuração do OAuth de terceiros para que os agentes conversacionais (Dialogflow CX) troquem um token de acesso do sistema OAuth e o adicionem no cabeçalho HTTP de autorização. Apenas é suportado o fluxo de credenciais de cliente. Recomendamos que forneça o segredo do cliente através do Secret Manager.
Tokens de acesso de agentes de serviço	Descontinuado
Conta de serviço	Pode usar uma conta de serviço para a autenticação. Pode usar esta opção para aceder a outras APIs Google Cloud.
Tokens de ID de agente de serviço	Pode 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. Pode ser usado para aceder aos recursos do Cloud Run.
Autenticação TLS mútua	Consulte a documentação sobre a autenticação TLS mútua.

Nota: se estiverem ativadas várias opções de autenticação, as opções de prioridade mais elevada têm 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.

Nota: não recomendamos a utilização de intervalos de IP para autenticar pedidos de webhook. Caso opte por usar o IP de origem do pedido para ativar a conetividade no perímetro da sua rede, tem de permitir pedidos dos intervalos indicados em https://www.gstatic.com/ipranges/goog.json e, em seguida, recusar quaisquer ligações dos intervalos indicados em https://www.gstatic.com/ipranges/cloud.json (que são endereços da Google que podem ser usados para implementar cargas de trabalho de terceiros). Além disso, o Dialogflow não pode oferecer garantias sobre os intervalos de IP para máquinas que enviam pedidos de webhook.

Nota: após 15 de agosto de 2025, os agentes exportados vão deixar de conter credenciais de valor não processado para cabeçalhos de autenticação, autenticação básica com nome de utilizador e palavra-passe, e OAuth de terceiros.

OAuth de terceiros

Os agentes conversacionais (Dialogflow CX) podem recolher um token de acesso de um fornecedor OAuth de terceiros e adicioná-lo ao cabeçalho HTTP de autorização quando fazem os respetivos pedidos de webhook.

A descrição seguinte descreve as definições de recursos para o OAuth de terceiros:

Vigência	Definição
ID do cliente	O ID de cliente a usar quando solicitar um token OAuth.
Segredo do cliente	O segredo a usar quando pedir um token OAuth. Recomendamos que forneça o segredo do cliente através do Secret Manager.
URL do ponto final OAuth	O URL a usar para pedir um token OAuth.
Âmbitos do OAuth	Uma lista separada por vírgulas de âmbitos para os quais o token OAuth pode ser usado.

Os pedidos enviados para o URL do ponto final OAuth para receber um token não incluem os cabeçalhos dos pedidos personalizados configurados para o pedido do webhook. Pode transmitir informações personalizadas para o servidor OAuth como parâmetros na string de consulta do URL do ponto final OAuth.

Nota: os tokens OAuth de terceiros são reutilizados para pedidos de webhook que usam o mesmo ID do cliente, URL do ponto final e âmbitos no mesmo agente de agentes conversacionais (Dialogflow CX), desde que o pedido seja feito no mesmo servidor de agentes conversacionais (Dialogflow CX) e o token não tenha expirado. Para alcançar uma elevada disponibilidade, os agentes são implementados em vários servidores individuais que não partilham caches de tokens OAuth. Ao implementar uma solução que usa tokens OAuth de terceiros, pondere cuidadosamente implementar um proxy de API para ajudar a gerir o volume de pedidos que o seu agente pode enviar ao seu fornecedor OAuth de terceiros.

Token de ID do agente do serviço

Os agentes de conversação (Dialogflow CX) podem gerar um token de ID através do agente de serviço dos agentes de conversação (Dialogflow CX).

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

Um token de ID pode ser usado para aceder aos recursos do Cloud Run depois de conceder autorizações da função Invoker a

[e-mail]

Se os recursos do Cloud Run estiverem no mesmo projeto de recursos, não precisa de autorização do IAM adicional para os chamar.

O público-alvo usado para gerar o token de ID será o URL completo do webhook, exceto os parâmetros de consulta. Se estiver a usar o Cloud Run, certifique-se de que este URL é suportado pelos 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 tem de estar nos públicos-alvo personalizados.

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

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

Conta de serviço

As contas de serviço podem ser usadas para autenticar pedidos de webhook em quaisquer APIs Google que o suportem.

Se ainda não o tiver feito, crie uma conta de serviço.

Uma vez que as contas de serviço são principais, podem aceder a recursos no seu projeto concedendo-lhe uma função, tal como faria para qualquer outro principal. O email da conta de serviço é usado para gerar um token de acesso, que é enviado no cabeçalho Authorization do pedido de webhook.

O utilizador que está a configurar o webhook para usar contas de serviço tem de ter as seguintes autorizações:

• roles/iam.serviceAccountUser

Para que os agentes conversacionais (Dialogflow CX) gerem tokens, o agente do serviço Dialogflow tem de ter as seguintes autorizações:

• roles/iam.serviceAccountTokenCreator

A conta de serviço também tem de ter autorizações para aceder ao serviço que está a alojar o webhook.

Nota: se estiver a tentar usar contas de serviço em vários projetos, certifique-se de que a sua política da organização o permite. Ambas as autorizações têm de ser concedidas no projeto que contém a conta de serviço.

Autenticação do Secret Manager

Se usar cabeçalhos de autenticação, autenticação básica com nome de utilizador e palavra-passe ou OAuth de terceiros, pode armazenar as credenciais como segredos através do Secret Manager. Seguem-se os passos necessários para autenticar o webhook através de segredos:

1. Crie o seu segredo se ainda não tiver um.
2. Conceda ao agente do serviço Dialogflow a função Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) no novo segredo.
3. Copie a credencial para a área de transferência.
4. Adicione uma nova versão do segredo ao seu segredo. Cole a credencial como o valor secreto.
   • Se usar cabeçalhos de autenticação, introduza Bearer <YOUR_CREDENTIAL>.
   • Se usar a autenticação básica de nome de utilizador e palavra-passe, introduza <YOUR_USERNAME>:<YOUR_PASSWORD>.
   • Omita qualquer caráter de nova linha no final.
5. Copie o nome da versão do Secret que acabou de adicionar. O formato do nome é projects/{project_id}/secrets/{secret_id}/versions/{version_id}".
6. Abra o ecrã de edição do webhook e, de seguida:
   • Se usar cabeçalhos de autenticação, crie um novo cabeçalho de pedido de versão secreta. Introduza "Autorização" como Chave e cole o nome da versão do Secret na caixa de entrada Versão do Secret.
   • Se usar a autenticação básica de nome de utilizador e palavra-passe, clique em Versão do segredo em Autenticação básica e cole o nome da versão do segredo na caixa de entrada Versão do segredo.
   • Se usar o OAuth de terceiros, clique em Versão secreta em OAuth de terceiros e cole o nome da versão secreta na caixa de entrada Versão secreta.
7. Clique em Guardar.

Nota: só suportamos o Secret Manager global. A utilização de segredos regionais não é suportada.

Validação do certificado HTTPS

Os agentes conversacionais (Dialogflow CX) usam por predefinição o repositório fidedigno predefinido da Google para validar os certificados HTTPS. Se pretender usar certificados não reconhecidos pelo repositório fidedigno predefinido da Google para o seu servidor HTTPS, como certificados autoassinados ou certificados de raiz personalizados, consulte o artigo Certificados de AC personalizados.

Webhooks específicos do ambiente

Se estiver a usar ambientes para isolar os sistemas de produção dos sistemas de desenvolvimento (recomendado), pode configurar os webhooks para serem específicos do ambiente. Para cada recurso de webhook que definir, pode fornecer um URL e definições de autenticação únicos para cada ambiente que definiu para o agente.

Isto permite-lhe desenvolver e testar em segurança as atualizações do código do webhook antes de as implementar na produção.

Crie ou edite recursos de webhook

Depois de ter um serviço de webhook em execução, tem de criar um recurso de webhook no seu agente com informações de conetividade e autenticação. Após a criação, também pode editar as definições de recursos de webhook em qualquer altura.

Para criar ou editar um recurso de webhook:

Consola

1. Abra a consola do Dialogflow CX.
2. Escolha o seu projeto do Google Cloud.
3. Selecione o seu agente.
4. Selecione o separador Gerir.
5. Clique em Webhooks.
6. Clique em Criar ou clique num recurso de webhook na lista para editar.
7. Introduza definições de recursos de webhook padrão ou definições de recursos de webhook flexíveis.
8. Clique em Guardar.

API

Para criar um recurso de webhook, consulte o método create para o tipo Webhook. Para editar um recurso de webhook (exceto as definições específicas do ambiente), consulte o método patch ou update para o tipo Webhook. Aceda à 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 de webhook	Interface de webhook
C++	WebhooksClient	Não disponível
C#	WebhooksClient	Não disponível
Go	WebhooksClient	Não disponível
Java	WebhooksClient	WebhooksClient
Node.js	WebhooksClient	WebhooksClient
PHP	Não disponível	Não disponível
Python	WebhooksClient	WebhooksClient
Ruby	Não disponível	Não disponível

Close

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

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

Protocolo	V3	V3beta1
REST	Recurso do ambiente	Recurso do ambiente
RPC	Interface do ambiente	Interface do ambiente
C++	EnvironmentsClient	Não disponível
C#	EnvironmentsClient	Não disponível
Go	EnvironmentsClient	Não disponível
Java	EnvironmentsClient	EnvironmentsClient
Node.js	EnvironmentsClient	EnvironmentsClient
PHP	Não disponível	Não disponível
Python	EnvironmentsClient	EnvironmentsClient
Ruby	Não disponível	Não disponível

Close

Erros de webhook

Se o seu serviço de webhook encontrar um erro ao processar um pedido de webhook, o seu código de webhook deve devolver um dos seguintes códigos de estado HTTP:

• 400 Pedido incorreto
• 401 Não autorizado
• 403 Proibido
• 404 Não encontrado
• 500 Falha do servidor
• 503 Serviço indisponível

Em qualquer uma das seguintes situações de erro, os agentes conversacionais (Dialogflow CX) invocam um erro ou um limite de tempo limite do webhook evento incorporado e continuam o processamento como habitualmente:

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

Além disso, se a chamada de serviço do webhook tiver sido acionada por uma chamada API detect intent, o campo queryResult.webhookStatuses na resposta detect intent contém as informações de estado do webhook.

Novas tentativas automáticas

Os agentes conversacionais (Dialogflow CX) incluem mecanismos internos que repetem automaticamente em caso de determinados erros de webhook para melhorar a robustez. Só são repetidos os erros não terminais (por exemplo, erros de limite de tempo ou de ligação).

Para reduzir a probabilidade de chamadas duplicadas:

• Defina limites de tempo limite de webhook mais longos.
• Suporte a idempotência na lógica do webhook ou remova duplicados.

Usar o Cloud Run

Nota: esta secção descreve como usar recursos do Cloud Run seguros para webhooks de agentes conversacionais (Dialogflow CX). Recomendamos que mantenha os seus recursos seguros. No entanto, se optar por fazer a autenticação com um nome de utilizador e uma palavra-passe baseados em URL ou cabeçalhos HTTP, deve permitir o acesso não autenticado ao seu recurso do Cloud Run.

Os agentes conversacionais (Dialogflow CX) integram-se com o Cloud Run, para que possa criar um webhook seguro e sem servidor. Se criar um recurso do Cloud Run que resida no mesmo projeto que o seu agente, selecione Service Agent Auth -> ID Token na configuração de autorização para que o seu agente possa chamar o webhook de forma segura.

No entanto, existem duas situações em que tem de configurar manualmente esta integração:

1. A conta de serviço do agente de serviço de agentes conversacionais (Dialogflow CX) com o seguinte endereço tem de existir para o projeto do seu agente:

   [e-mail]

   Esta conta de serviço especial e a chave associada são normalmente criadas automaticamente quando cria o primeiro agente para um projeto. Se o seu agente foi criado antes de 1 de novembro de 2020, pode acionar 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 sua função de webhook residir num projeto diferente do agente, tem de fornecer a função do IAM Cloud Run Invoker ou Cloud Functions Invoker à conta de serviço do agente de serviço de agentes conversacionais (Dialogflow CX) no projeto do seu recurso do Cloud Run.
3. Selecione Service Agent Auth -> ID Token na secção de configuração de autorização.

Usar webhooks em contentores e o framework Go ezcx

Se quiser implementar um webhook em contentor com o Go, consulte a estrutura Go ezcx. Esta estrutura pode simplificar muitos dos passos necessários ao criar um webhook.

Usar o Cloud Run com tráfego apenas interno

Nota: a utilização do Cloud Run fora do perímetro do VPC Service Controls do projeto do agente de agentes conversacionais (Dialogflow CX) para webhooks não é suportada.

Os recursos do Cloud Run configurados para aceitar tráfego interno de redes VPC no mesmo projeto ou no mesmo perímetro do VPC Service Controls podem ser usados como um webhook, desde que o agente esteja no mesmo projeto ou no mesmo perímetro do VPC Service Controls.

Usar o Service Directory para acesso à rede privada

Os agentes conversacionais (Dialogflow CX) integram-se com o acesso à rede privada do Service Directory, para que possam estabelecer ligação a destinos de webhook na sua rede VPC. Isto mantém o tráfego na rede do Google Cloud e aplica o IAM e os VPC Service Controls.

Para configurar um webhook que segmente uma rede privada:

1. Siga a configuração da rede privada do Service Directory para configurar a sua rede VPC e o ponto final do Service Directory.

   Nota: os agentes conversacionais (Dialogflow CX) armazenam em cache as informações do diretório de serviços durante 90 segundos. Isto significa que, se atualizar o ponto final do diretório de serviços, a alteração demora 90 segundos a ocorrer. Além disso, se estiver a configurar vários pontos finais para redundância, os agentes conversacionais (Dialogflow CX) podem enviar tráfego através de um ponto final com falhas durante 90 segundos.

2. A conta de serviço do agente de serviço de agentes conversacionais (Dialogflow CX) com o seguinte endereço tem de existir para o projeto do seu agente:

   [e-mail]

   Conceda as seguintes funções à conta de serviço do agente de serviço de agentes conversacionais (Dialogflow CX) no projeto onde se encontra o seu Service Directory:

   • servicedirectory.viewer
   • servicedirectory.pscAuthorizedService

   Além disso, se o Service Directory estiver num projeto diferente do seu agente do Dialogflow CX, também tem de conceder a função servicedirectory.viewer à conta do agente de serviço dos agentes conversacionais (Dialogflow CX) no projeto que aloja o seu agente do Dialogflow CX.

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

   Consola

   

   API

   Consulte o campo serviceDirectory para o tipo Webhook. Aceda à 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 de webhook	Interface de webhook
   C++	WebhooksClient	Não disponível
   C#	WebhooksClient	Não disponível
   Go	WebhooksClient	Não disponível
   Java	WebhooksClient	WebhooksClient
   Node.js	WebhooksClient	WebhooksClient
   PHP	Não disponível	Não disponível
   Python	WebhooksClient	WebhooksClient
   Ruby	Não disponível	Não disponível

   Close

Para resolver problemas, pode configurar uma verificação de tempo de atividade privada para verificar se o diretório de serviços está configurado corretamente.

Exemplos e resolução de problemas

Consulte o guia de instruções sobre webhooks.