Webhooks

Los webhooks son servicios que alojan tu lógica empresarial o llaman a otros servicios. Durante una sesión, los webhooks te permiten usar los datos extraídos por el procesamiento de lenguaje natural de Dialogflow CX para generar respuestas dinámicas, validar datos recopilados o activar acciones en el backend.

Un webhook puede ser un webhook estándar o un webhook flexible. Con un webhook estándar, Dialogflow CX define los campos de solicitud y respuesta. Con un webhook flexible, defines los campos de solicitud y respuesta.

También puedes acceder al código de estado HTTP de la llamada al webhook con el parámetro de solicitud $request.webhook_status_code.

Webhooks estándar

Con los webhooks estándar, usas los mensajes de solicitud y respuesta definidos por Dialogflow CX. El mensaje de solicitud proporciona muchos detalles sobre la sesión. Por ejemplo, se incluyen la página activa actual, el intent coincidente reciente, los valores de los parámetros de sesión y las respuestas definidas por el agente.

Solicitud de webhook estándar

Cuando se llama a un cumplimiento con un webhook, Dialogflow CX envía una solicitud de webhook HTTPS POST a tu servicio de webhook. El cuerpo de esta solicitud es un objeto JSON WebhookRequest con información sobre la sesión.

Algunas integraciones propagan el campo WebhookRequest.payload con información adicional. Por ejemplo, la integración de Dialogflow CX Phone Gateway proporciona el ID de emisor del usuario final.

Para obtener más detalles, consulta la documentación de referencia de WebhookRequest (V3) o WebhookRequest (V3Beta1).

Respuesta estándar del webhook

Después de que tu servicio de webhook reciba una solicitud, debe enviar una respuesta que cumpla con estos requisitos:

• La respuesta debe ocurrir dentro del tiempo de espera configurado cuando se crea el recurso de webhook.
• La respuesta debe ser de 64 KiB o menos.

Para obtener más detalles, consulta la documentación de referencia de WebhookResponse (V3) o WebhookResponse (V3Beta1).

Configuración de recursos de webhook estándar

En la siguiente tabla, se describen los parámetros de configuración de los recursos de webhook para los webhooks estándar:

X	Elemento
Nombre visible	Es el nombre que se muestra en la consola para el webhook.
Tiempo de espera del webhook	Cuando Dialogflow CX envía una solicitud HTTP a tu servicio de webhook, este parámetro de configuración controla el tiempo de espera en segundos para cada intento de solicitud individual, no para el turno de conversación general. Si un intento se agota o falla con un error transitorio, Dialogflow CX vuelve a intentarlo automáticamente una vez. Este reintento puede generar un tiempo de respuesta total de hasta el doble del valor de tiempo de espera configurado antes de que se devuelva un error. Si se agota el tiempo de espera después de reintentar, Dialogflow CX invoca un evento webhook.error.timeout. Para obtener más información, consulta Reintentos automáticos.
Tipo	Establécelo en Directorio de servicios si usas el Directorio de servicios para el acceso a redes privadas; de lo contrario, establécelo en Servicio web genérico.
URL de webhook	Proporciona la dirección URL de tu servicio de webhook.
Subtipo	Establécelo en Estándar.
Webhook específico del entorno	Puedes proporcionar webhooks específicos del entorno.
Autenticación	Consulta la sección Autenticación.
Certificado de la AC personalizado	Se usa para subir certificados de la AC personalizados.

Webhooks flexibles

Con los webhooks flexibles, defines el método HTTP de la solicitud, los parámetros de URL de la solicitud y los campos de los mensajes de solicitud y respuesta. La solicitud solo puede proporcionar valores de parámetros seleccionados, y la respuesta solo puede proporcionar valores de anulación de parámetros. Esto simplifica la interfaz entre el agente y el webhook, ya que rara vez es necesario comunicar algo que no sean los valores de los parámetros de sesión. También simplifica la implementación de tu webhook, ya que los mensajes de solicitud y respuesta solo contienen lo que necesitas, y puedes proporcionar mensajes de webhook únicos para varios casos de uso.

Solicitud de webhook flexible

Cuando creas el recurso de webhook para tu agente, puedes especificar lo siguiente para las solicitudes de webhook:

• Es el método HTTP que se usa para las solicitudes de webhook que se envían a tu servicio de webhook.
• Son los valores de los parámetros de sesión que Dialogflow CX debe enviar a tu servicio de webhook con la URL.
• Son los valores de los parámetros de sesión que Dialogflow CX debe enviar a tu servicio de webhook a través del cuerpo JSON de la solicitud si eliges POST, PUT o PATCH como método.

Para enviar valores de parámetros de sesión con la URL de la solicitud o el cuerpo JSON, usa referencias de parámetros. No es necesario que uses caracteres de escape de URL en la referencia del parámetro ni que la encierres entre comillas. En el entorno de ejecución, Dialogflow CX escapa la URL del valor del parámetro según sea necesario. Se proporciona una lista o un valor compuesto como JSON.

Cuando uses una referencia de parámetro en el cuerpo de JSON, debes unir la referencia entre comillas, sin importar el tipo de parámetro. Si el parámetro es, en realidad, un valor escalar, de lista o compuesto numérico, Dialogflow CX quitará las comillas cuando envíe la solicitud en el entorno de ejecución para conservar el tipo de datos del parámetro. Los tipos escalares de cadena permanecerán entre comillas. Si se hace referencia a un valor escalar, de lista o compuesto numérico dentro de un valor de cadena (por ejemplo: "Este es un número: $session.params.size"), el parámetro se tratará como una cadena ("Este es un número: 3").

Por ejemplo, puedes proporcionar los valores de los parámetros de sesión fruit y size a la URL de la solicitud de la siguiente manera:

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

Y al cuerpo JSON de la solicitud, de la siguiente manera:

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

Respuesta de webhook flexible

Cuando creas el recurso de webhook para tu agente, puedes especificar los parámetros de sesión que Dialogflow CX debe establecer en campos específicos de la respuesta del webhook en el entorno de ejecución.

Tu respuesta debe cumplir con las siguientes limitaciones:

• La respuesta debe ocurrir dentro del tiempo de espera configurado cuando se crea el recurso de webhook; de lo contrario, se agotará el tiempo de espera de la solicitud.
• La respuesta debe tener un tamaño máximo de 64 KiB.

Para especificar un campo escalar, de lista o compuesto, usa el siguiente formato:

$.fully.qualified.path.to.field

Por ejemplo, considera la siguiente respuesta JSON:

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

Para especificar el campo "value", usa lo siguiente:

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

Configuración flexible de recursos de webhook

En la siguiente tabla, se describe la configuración de los recursos de webhook para los webhooks flexibles.

X	Elemento
Nombre visible	Es el nombre que se muestra en la consola para el webhook.
Tiempo de espera del webhook	Cuando Dialogflow CX envía una solicitud HTTP a tu servicio de webhook, este parámetro de configuración controla el tiempo de espera en segundos para cada intento de solicitud individual, no para el turno de conversación general. Si un intento se agota o falla con un error transitorio, Dialogflow CX vuelve a intentarlo automáticamente una vez. Este reintento puede generar un tiempo de respuesta total de hasta el doble del valor de tiempo de espera configurado antes de que se devuelva un error. Si se agota el tiempo de espera después de reintentar, Dialogflow CX invoca un evento webhook.error.timeout. Para obtener más información, consulta Reintentos automáticos.
Tipo	Establécelo en Directorio de servicios si usas el Directorio de servicios para el acceso a la red privada; de lo contrario, establécelo en Servicio web genérico.
URL de webhook	Proporciona la dirección URL de tu servicio de webhook, que puede incluir referencias a parámetros de sesión.
Subtipo	Establécelo en Flexible.
Método	Establece el método HTTP para la solicitud de webhook.
Cuerpo de la solicitud	Proporciona el cuerpo JSON de la solicitud como se describió anteriormente.
Configuración de la respuesta	Proporciona los parámetros de sesión que se deben establecer en los campos de respuesta como se describió anteriormente.
Webhook específico del entorno	Puedes proporcionar webhooks específicos del entorno.
Autenticación	Consulta la sección de autenticación.
Certificado de la AC personalizado	Se usa para subir certificados de la AC personalizados.

Usa una plantilla personalizada predefinida

Dialogflow ofrece plantillas personalizadas predefinidas que puedes usar para integrar webhooks flexibles con Salesforce CRM.

1. Ve a la pestaña Administrar, selecciona Webhooks y, luego, haz clic en Crear.
2. En Subtipo, selecciona Flexible.
3. Haz clic en Configurar con una plantilla predefinida.
4. En el menú Tipo de integración, selecciona Salesforce.
5. En el menú Nombre de la API, selecciona un nombre de API. La plantilla completa automáticamente el formulario de webhook según el nombre de la API que elijas.
   1. Configura de forma manual los siguientes campos, si corresponde, según tus parámetros:
      • URL de webhook
      • Método
      • JSON del cuerpo de la solicitud
      • Configuración de la respuesta
   2. Los campos de OAuth obligatorios se destacarán en la sección Autenticación.
6. Haz clic en Guardar.

Requisitos del servicio de webhook

Tu servicio de webhook debe cumplir con los siguientes requisitos:

• Controlar solicitudes HTTPS No se admite HTTP. Si alojas tu servicio de webhook en Google Cloud con una solución de Compute o de computación sin servidores, consulta la documentación para realizar entregas con HTTPS. Para conocer otras opciones de hosting, consulta Obtén un certificado SSL para tu dominio.
• Asegúrate de que la URL del servicio de webhook sea de acceso público, a menos que se aloje como un recurso de Cloud Run o se acceda como un webhook del Directorio de servicios.
• Controla las solicitudes y respuestas como se describe en la sección webhook estándar o webhook flexible.
• Si tu agente no se integra en el acceso a la red privada del Directorio de servicios, las llamadas de webhook están fuera del perímetro de servicio y se bloquean cuando se habilitan los Controles del servicio de VPC. El Directorio de servicios admite extremos limitados. Para obtener más detalles, consulta Directorio de servicios.

Autenticación

Protege tu servicio de webhook para que solo tú o tu agente de Dialogflow CX puedan realizar solicitudes. Configura esto cuando crees o edites un recurso de webhook. Dialogflow CX admite los siguientes mecanismos de autenticación:

X	Elemento
Encabezados de autenticación	En la configuración del webhook, puedes especificar pares clave-valor opcionales del encabezado HTTP. Si se proporcionan, Dialogflow CX agrega estos encabezados HTTP a las solicitudes de webhook. Es común proporcionar un solo par con una clave de authorization. Los valores de encabezado admiten referencias de parámetros de sesión y análisis de funciones del sistema, como en los mensajes de respuesta estáticos. Si usas una credencial estática para el encabezado authorization, te recomendamos que proporciones tu credencial con Secret Manager.
Autenticación básica con nombre de usuario y contraseña	En la configuración del webhook, puedes especificar valores opcionales de nombre de usuario y contraseña de acceso. Si se proporciona, Dialogflow CX agrega un encabezado HTTP de autorización a las solicitudes de webhook. Este encabezado tiene el siguiente formato: "authorization: Basic <base 64 encoding of the string username:password>". Te recomendamos que proporciones tu nombre de usuario y contraseña con Secret Manager.
OAuth de terceros	Puedes especificar la configuración de OAuth de terceros para que Dialogflow CX intercambie un token de acceso del sistema de OAuth y lo agregue en el encabezado HTTP de autorización. Solo se admite el flujo de credenciales de cliente. Te recomendamos que proporciones tu secreto del cliente con Secret Manager.
Tokens de acceso del agente de servicio	Se descontinuó.
Cuenta de servicio	Puedes usar una cuenta de servicio para la autenticación. Esto se puede usar para acceder a otras APIs de Google Cloud .
Tokens de ID del agente de servicio	Puedes elegir el token de ID en la sección Autenticación del agente de servicio, que te permite usar el token de ID del agente de servicio para la autenticación. Esto te permite acceder a los recursos de Cloud Run.
Autenticación TLS mutua	Consulta la documentación de Autenticación TLS mutua.

Nota: Si se habilitan varias opciones de autenticación, las opciones de mayor prioridad tienen prioridad. El orden de prioridad es el siguiente: Encabezados de autenticación, autenticación básica, OAuth de terceros, autenticación de agente de servicio.

Nota: No recomendamos usar rangos de IP para autenticar solicitudes de webhook. Si eliges usar la IP de origen de la solicitud para habilitar la conectividad en el perímetro de tu red, permite las solicitudes de los rangos que se indican en https://www.gstatic.com/ipranges/goog.json y rechaza las conexiones de los rangos que se indican en https://www.gstatic.com/ipranges/cloud.json (estas son las direcciones de Google que se pueden usar para implementar cargas de trabajo de terceros). Dialogflow no puede garantizar los rangos de IP para las máquinas que envían solicitudes de webhook.

Nota: Después del 15 de agosto de 2025, los agentes exportados ya no contendrán credenciales de valor sin procesar para los encabezados de autenticación, la autenticación básica con nombre de usuario y contraseña, ni OAuth de terceros.

OAuth de terceros

Dialogflow CX recopila un token de acceso de un proveedor de OAuth de terceros y lo agrega al encabezado HTTP de autorización cuando realiza solicitudes de webhook.

En la siguiente tabla, se describen los parámetros de configuración de recursos para OAuth de terceros:

X	Elemento
ID de cliente	Es el ID de cliente que se usará cuando se solicite un token de OAuth.
Secreto del cliente	Es el secreto que se usará cuando se solicite un token de OAuth. Te recomendamos que proporciones tu secreto del cliente con Secret Manager.
URL del extremo de OAuth	Es la URL que se debe usar para solicitar un token de OAuth.
Permisos de OAuth	Es una lista separada por comas de los permisos para los que se puede usar el token de OAuth.

Las solicitudes que se envían a la URL del endpoint de OAuth para recibir un token no incluyen los encabezados de la solicitud personalizados configurados para la solicitud de webhook. Puedes pasar información personalizada al servidor de OAuth como parámetros dentro de la cadena de consulta de la URL del extremo de OAuth.

Nota: Los tokens de OAuth de terceros se reutilizan para las solicitudes de webhook que usan el mismo ID de cliente, la URL del extremo y los permisos dentro del mismo agente de Dialogflow CX, siempre y cuando la solicitud se realice en el mismo servidor de Dialogflow CX y el token no haya vencido. Para lograr una alta disponibilidad, los agentes se implementan en muchos servidores individuales que no comparten cachés de tokens de OAuth. Cuando implementes una solución que use tokens de OAuth de terceros, considera cuidadosamente implementar un proxy de API para ayudar a administrar el volumen de solicitudes que tu agente puede enviar a tu proveedor de OAuth de terceros.

Token de ID del agente de servicio

Dialogflow CX puede generar un token de ID con el agente de servicio de Dialogflow CX. Este token se agrega al encabezado HTTP de autorización cuando Dialogflow CX llama a un webhook.

Se puede usar un token de ID para acceder a los recursos de Cloud Run después de otorgar el rol de Invocador de Cloud Run (roles/run.invoker) a

service-agent-project-number@gcp-sa-dialogflow.

Si los recursos de Cloud Run están en el mismo proyecto de recursos, no necesitas permisos adicionales de Identity and Access Management (IAM) para llamarlos.

El público que se usa para generar el token de ID es la URL de webhook completa, sin incluir los parámetros de consulta. Si usas Cloud Run, asegúrate de que esta URL sea compatible con los públicos de Cloud Run.

Por ejemplo, si la URL de webhook es la siguiente:

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

la siguiente URL debe estar en los públicos personalizados:

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

Cualquier webhook también puede validar el token de forma opcional con las bibliotecas cliente de Google o las bibliotecas de código abierto, como la biblioteca de Google Auth para Node.js.

Si tu webhook está alojado en Cloud Run y se accede a él a través de un balanceador de cargas, agrega la URL de tu balanceador de cargas como un público personalizado a tu Cloud Run. Para obtener más información sobre los públicos personalizados, consulta Configura públicos personalizados para los servicios.

Cuenta de servicio

Las cuentas de servicio se pueden usar para autenticar solicitudes de webhook a cualquier API de Google que las admita.

Si aún no lo hiciste, crea una cuenta de servicio.

Debido a que las cuentas de servicio son principales, pueden acceder a los recursos de tu proyecto si les otorgas un rol, al igual que cualquier otra principal. El correo electrónico de la cuenta de servicio se usa para generar un token de acceso que se envía en el encabezado Authorization de la solicitud de webhook.

Para configurar el webhook de modo que use cuentas de servicio, debes tener los siguientes permisos:

• roles/iam.serviceAccountUser

Para generar tokens, el agente de servicio de Dialogflow debe tener los siguientes permisos:

• roles/iam.serviceAccountTokenCreator

La cuenta de servicio también debe tener permisos para acceder al servicio que aloja el webhook.

Nota: Si intentas usar cuentas de servicio en varios proyectos, asegúrate de que la política de la organización lo admita. Ambos permisos se deben otorgar en el proyecto que contiene la cuenta de servicio.

Autenticación de Secret Manager

Si usas encabezados de autenticación, autenticación básica con nombre de usuario y contraseña, o OAuth de terceros, puedes almacenar las credenciales como secrets con Secret Manager. A continuación, se indican los pasos necesarios para autenticar tu webhook con secretos:

1. Crea tu secreto si no tienes uno.
2. Otorga al agente de servicio de Dialogflow el rol de descriptor de acceso a secretos de Secret Manager (roles/secretmanager.secretAccessor) en el secreto nuevo.
3. Copia tu credencial en el portapapeles.
4. Agrega una versión nueva del Secret a tu Secret y pega tu credencial como el valor del Secret:
   • Si usas encabezados de autenticación, ingresa Bearer <YOUR_CREDENTIAL>.
   • Si usas la autenticación básica de nombre de usuario y contraseña, ingresa <YOUR_USERNAME>:<YOUR_PASSWORD>.
   • Omite cualquier carácter de línea nueva al final.
5. Copia el nombre de la versión del secreto que agregaste. El formato del nombre es projects/<var>PROJECT_ID</var>/secrets/<var>SECRET_ID</var>/versions/<var>VERSION_ID</var>.
6. Abre la pantalla de edición del webhook.
7. Establece la configuración de autenticación:
   • Si usas encabezados de autenticación, crea un nuevo encabezado de la solicitud de versión del Secret. Ingresa "Authorization" en el campo Clave y pega el nombre de la versión del Secret en el campo Versión del Secret.
   • Para la autenticación básica de nombre de usuario y contraseña, haz clic en Versión del secreto en Autenticación básica y pega el nombre de la versión del secreto en el campo Versión del secreto.
   • Si usas OAuth de terceros, haz clic en Versión del Secret en OAuth de terceros y pega el nombre de la versión del Secret en el campo Versión del Secret.
8. Haz clic en Guardar.

Nota: Solo admitimos secretos globales de Secret Manager. No admitimos secrets regionales.

Verificación de certificados HTTPS

De forma predeterminada, Dialogflow CX usa el almacén de confianza predeterminado de Google para verificar los certificados HTTPS. Si tienes la intención de usar certificados que el almacén de confianza predeterminado de Google no reconoce para tu servidor HTTPS, como certificados autofirmados o certificados raíz personalizados, consulta Certificados de AC personalizados.

Webhooks específicos del entorno

Si usas entornos para aislar la producción del desarrollo, puedes configurar tus webhooks para que sean específicos del entorno. Puedes proporcionar la URL y la configuración de autenticación específicas del entorno para cada recurso de webhook.

Esta configuración te permite desarrollar y probar de forma segura las actualizaciones del código de webhook antes de implementarlas en producción.

Crea o edita recursos de webhook

Después de que tengas un servicio de webhook en ejecución, crea un recurso de webhook en tu agente que incluya información de conectividad y autenticación. Puedes editar la configuración de los recursos de webhook en cualquier momento.

Para crear o editar un recurso de webhook, sigue estos pasos:

Console

1. Abre la consola de Dialogflow CX.
2. Ve a tu proyecto.
3. Selecciona el agente.
4. Haz clic en la pestaña Administrar.
5. Haz clic en Webhooks.
6. Haz clic en Crear o selecciona un webhook existente para editarlo.
7. Configura los parámetros de configuración del recurso de webhook estándar o los parámetros de configuración del recurso de webhook flexible.
8. Haz clic en Guardar.

API

Para obtener información sobre cómo crear un recurso de webhook, consulta el método create para el tipo Webhook. Para obtener información sobre cómo editar un recurso de webhook (excepto la configuración específica del entorno), consulta el método patch o update para el tipo Webhook. Ir a la referencia de la API de Webhook

Selecciona un protocolo y una versión para la referencia de webhook:

Protocolo	V3	V3beta1
REST	Recurso de webhook	Recurso de webhook
RPC	Interfaz de webhook	Interfaz de webhook
C++	WebhooksClient	No disponible
C#	WebhooksClient	No disponible
Go	WebhooksClient	No disponible
Java	WebhooksClient	WebhooksClient
Node.js	WebhooksClient	WebhooksClient
PHP	No disponible	No disponible
Python	WebhooksClient	WebhooksClient
Ruby	No disponible	No disponible

Cerrar

Para obtener información sobre cómo editar la configuración específica del entorno de un webhook, consulta el método patch o update para el tipo Environment. Ir a la referencia de la API de entorno

Selecciona un protocolo y una versión para la referencia del entorno:

Protocolo	V3	V3beta1
REST	Recurso de entorno	Recurso de entorno
RPC	Interfaz del entorno	Interfaz del entorno
C++	EnvironmentsClient	No disponible
C#	EnvironmentsClient	No disponible
Go	EnvironmentsClient	No disponible
Java	EnvironmentsClient	EnvironmentsClient
Node.js	EnvironmentsClient	EnvironmentsClient
PHP	No disponible	No disponible
Python	EnvironmentsClient	EnvironmentsClient
Ruby	No disponible	No disponible

Cerrar

Errores de webhook

Si tu servicio de webhook encuentra un error mientras controla una solicitud de webhook, tu código de webhook debería devolver uno de los siguientes códigos de estado HTTP:

• 400: Solicitud incorrecta
• 401: Sin autorización
• 403: Acción prohibida
• 404: No se encontró
• 500: Falla del servidor
• 503: El servicio no está disponible

Dialogflow CX invoca un evento integrado de error o tiempo de espera de webhook y continúa el procesamiento como de costumbre en las siguientes situaciones de error:

• Se supera el tiempo de espera de la respuesta.
• Se recibe un código de estado de error.
• La respuesta no es válida.
• El servicio de webhook no está disponible.

Si la llamada al servicio de webhook se activó mediante una llamada a la API de intent de detección, el campo queryResult.webhookStatuses de la respuesta de intent de detección contiene la información de estado del webhook.

Reintentos automáticos

Dialogflow CX reintenta automáticamente las solicitudes en ciertos errores de webhook para mejorar la solidez. Los reintentos automáticos están habilitados de forma predeterminada y no se pueden inhabilitar.

Dialogflow CX ejecuta un solo reintento para fallas transitorias, como tiempos de espera de solicitudes, conexiones de red interrumpidas y códigos de estado HTTP en el rango 5xx (como 500 Server fault o 503 Service unavailable). Los errores de cliente de terminal, como el código de estado HTTP 404 Not found, fallan de inmediato sin un reintento.

Latencia acumulativa y presupuesto de tiempo de espera

Debido a que Dialogflow CX reintenta las fallas transitorias una vez, un extremo de webhook que no responde puede generar un tiempo de respuesta acumulativo de hasta el doble del valor de tiempo de espera configurado antes de que Dialogflow CX devuelva un error. Por ejemplo, con el parámetro de configuración de tiempo de espera predeterminado de 5 segundos, un extremo que no responde agota el tiempo de espera después de 5 segundos en el intento inicial y después de otros 5 segundos en el intento de reintento. Esto genera una latencia total de aproximadamente 10 segundos antes de que Dialogflow CX invoque controladores de errores, como un controlador de eventos webhook.error.timeout o un controlador de eventos sys.no-match-default.

Si tu arquitectura tiene límites estrictos de latencia ascendente (como los sistemas de telefonía o de respuesta de voz interactiva [IVR] que finalizan las llamadas después de un período de tiempo de espera de 10 segundos), establece el tiempo de espera del webhook en la mitad del período permitido (por ejemplo, entre 2.5 y 4 segundos) para que se puedan realizar ambos intentos.

Prácticas recomendadas para los reintentos

Para controlar los reintentos de manera eficaz en tu servicio de webhook, haz lo siguiente:

• Implementa la idempotencia o la anulación de duplicación de solicitudes en la lógica del servicio de webhook para procesar de forma segura las solicitudes duplicadas.
• Si la operación del webhook tarda más que el tiempo de espera configurado, devuelve una respuesta inmediata con el código de estado HTTP 200 OK y un mensaje de resguardo, y procesa la tarea de larga duración de forma asíncrona.

con Cloud Run

Precaución: En esta sección, se describe cómo usar recursos seguros de Cloud Run para los webhooks de Dialogflow CX. Se recomienda mantener tus recursos protegidos. Si eliges autenticarte con un nombre de usuario y una contraseña basados en URL o con encabezados HTTP, debes permitir el acceso no autenticado a tu recurso de Cloud Run.

Dialogflow CX se integra en Cloud Run, por lo que puedes crear un webhook seguro y sin servidores. Si creas un recurso de Cloud Run que reside en el mismo proyecto que tu agente, selecciona Autenticación del agente de servicio y, luego, Token de ID en la configuración de autenticación para que tu agente pueda llamar a tu webhook de forma segura.

Debes configurar esta integración de forma manual en las siguientes dos situaciones:

1. La cuenta de servicio del agente de servicio de Dialogflow CX con la siguiente dirección debe existir para tu proyecto de agente:

   service-agent-project-number@gcp-sa-dialogflow.

   Esta cuenta de servicio especial y la clave asociada se crean automáticamente cuando creas el primer agente para un proyecto. Si tu agente se creó antes del 1 de noviembre de 2020, puedes activar la creación de esta cuenta de servicio especial:
   1. Crea un agente nuevo para el proyecto.
   2. Ejecuta el siguiente comando:

      gcloud beta services identity create --service=dialogflow.googleapis.com --project=agent-project-id

2. Si tu función de webhook reside en un proyecto diferente al del agente, debes proporcionar el rol de IAM de Invocador de Cloud Run o Invocador de Cloud Functions a la cuenta de servicio del agente de servicio de Dialogflow CX en tu proyecto de recursos de Cloud Run.

Luego, selecciona Autenticación del agente de servicio > Token de ID en la sección Configuración de autenticación.

Usa webhooks alojados en contenedores y el framework ezcx de Go

Para implementar un webhook alojado en contenedores con Go, consulta el framework de ezcx de Go. Este framework simplifica muchos de los pasos necesarios para crear un webhook.

Usa Cloud Run solo con tráfico interno

Nota: No se admite el uso de Cloud Run fuera del perímetro de los Controles del servicio de VPC del proyecto del agente de Dialogflow CX para webhooks.

Puedes usar recursos de Cloud Run configurados para aceptar tráfico interno desde redes de nube privada virtual (VPC) en el mismo proyecto o en el mismo perímetro de Controles del servicio de VPC como un webhook, siempre que el agente esté en el mismo proyecto o en el mismo perímetro de Controles del servicio de VPC.

Usa el Directorio de servicios para acceder a redes privadas

Dialogflow CX se integra en el acceso a la red privada del Directorio de servicios, por lo que puede conectarse a destinos de webhook dentro de tu red de VPC. Esto mantiene el tráfico dentro de la red de Google Cloud y aplica la IAM y los Controles del servicio de VPC.

Para configurar un webhook que se oriente a una red privada, sigue estos pasos:

1. Sigue la configuración de la red privada del Directorio de servicios para configurar tu red de VPC y el extremo del Directorio de servicios.

   Nota: Dialogflow CX almacena en caché la información del Directorio de servicios durante 90 segundos. Esto significa que, cuando actualizas el extremo del Directorio de servicios, el cambio tarda 90 segundos en producirse.

2. La cuenta de servicio del agente de servicio de Dialogflow CX con la siguiente dirección debe existir para tu proyecto de agente:

   service-agent-project-number@gcp-sa-dialogflow.

   Otorga los siguientes roles a la cuenta de servicio del agente de servicio de Dialogflow CX en el proyecto en el que se encuentra tu Directorio de servicios:

   • servicedirectory.viewer
   • servicedirectory.pscAuthorizedService

   Además, si tu Directorio de servicios se encuentra en un proyecto diferente del de tu agente de Dialogflow CX, también debes otorgar el rol servicedirectory.viewer a la cuenta del agente de servicio de Dialogflow CX en el proyecto que aloja tu agente de Dialogflow CX.

3. Especifica el servicio del Directorio de servicios, la URL y cualquier información de autenticación opcional cuando crees el webhook.

   Console

   

   API

   Consulta el campo serviceDirectory para el tipo Webhook. Ir a la referencia de la API de webhook.

   Selecciona un protocolo y una versión para la referencia de webhook:

   Protocolo	V3	V3beta1
   REST	Recurso de webhook	Recurso de webhook
   RPC	Interfaz de webhook	Interfaz de webhook
   C++	WebhooksClient	No disponible
   C#	WebhooksClient	No disponible
   Go	WebhooksClient	No disponible
   Java	WebhooksClient	WebhooksClient
   Node.js	WebhooksClient	WebhooksClient
   PHP	No disponible	No disponible
   Python	WebhooksClient	WebhooksClient
   Ruby	No disponible	No disponible

   Cerrar

Para solucionar problemas, puedes configurar una verificación de tiempo de actividad privada para comprobar que tu Directorio de servicios esté configurado correctamente.

Muestras y solución de problemas

Para obtener más información, consulta la guía práctica de webhooks.