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 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 una entrega 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 la puerta de enlace telefónica de Dialogflow CX proporciona el identificador de llamadas del usuario final.

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

Respuesta de webhook estándar

Después de que su 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 crees el recurso de webhook.
• La respuesta debe ser de 64 KiB o menor.

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

Configuración estándar de recursos de webhook

La siguiente tabla describe la configuración de recursos de webhook para 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 agota el tiempo de espera o falla con un error transitorio, Dialogflow CX lo vuelve a intentar 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 devolver un error. Si se produce un 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	Establece el valor en Directorio de servicios si usas el directorio de servicios para acceder a redes privadas. De lo contrario, establece el valor en Servicio web genérico.
URL de webhook	Proporciona la dirección URL de tu servicio de webhook.
Subtipo	Se establece 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 CA personalizados.

Webhooks flexibles

Con los webhooks flexibles, defines el método HTTP de la solicitud, los parámetros de la 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 más que 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 diversas situaciones.

Solicitud de webhook flexible

Cuando crees 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 a través de 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 escapes la referencia del parámetro con URL ni que la encierres entre comillas. En el tiempo de ejecución, Dialogflow CX aplica escape de URL al 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 JSON, debes incluir la referencia entre comillas, independientemente del tipo de parámetro. Si el parámetro es en realidad un valor escalar, una lista o un valor compuesto numérico, Dialogflow CX quitará las comillas cuando envíe la solicitud en el tiempo de ejecución para conservar el tipo de datos del parámetro. Los tipos de datos escalares de cadena permanecerán entre comillas. Si se hace referencia a un valor numérico escalar, una lista o un valor compuesto 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 de la solicitud JSON 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 parámetros de sesión que Dialogflow CX debe establecer en campos específicos de la respuesta del webhook durante el tiempo de ejecución.

Tu respuesta debe cumplir con las siguientes limitaciones:

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

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 describen los parámetros de 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 agota el tiempo de espera o falla con un error transitorio, Dialogflow CX lo vuelve a intentar 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 devolver un error. Si se produce un 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	Establece el valor en Directorio de servicios si usas el directorio de servicios para acceder a redes privadas. De lo contrario, establece el valor 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	Se establece 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 CA personalizados.

Usa una plantilla personalizada predefinida

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

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 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. Si corresponde, configura manualmente los siguientes campos según tus parámetros:
      • URL de webhook
      • Método
      • Cuerpo de la solicitud en formato JSON
      • Configuración de 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:

• Controla solicitudes HTTPS. No se admite HTTP. Si alojas tu servicio de webhook en Google Cloud con una solución de Compute o computación sin servidores, consulta la documentación para la entrega con HTTPS. Para conocer otras opciones de hosting, consulta Obtén un certificado SSL para tu dominio.
• Asegúrate de que se pueda acceder públicamente a la URL del servicio de webhook, a menos que se aloje como un recurso de Cloud Run o se acceda a él como un webhook del Directorio de servicios.
• Controla las solicitudes y respuestas como se describe en la sección de webhook estándar o webhook flexible.
• Si tu agente no se integra al acceso a la red privada del Directorio de servicios, las llamadas de webhook se consideran 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 información, 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 de webhook, puedes especificar pares clave-valor de encabezado HTTP opcionales. 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 de webhook, puedes especificar valores opcionales de nombre de usuario y contraseña para acceder. 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. 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 de 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 mutua de TLS	Consulta la documentación sobre la autenticación TLS mutua.

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

Nota: No recomendamos usar rangos de IP para autenticar solicitudes de webhook. Si decides usar la IP de origen de la solicitud para habilitar la conectividad en tu perímetro de 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 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 externo 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 usa cuando se solicita 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 usa 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 enviadas a la URL del extremo de OAuth para recibir un token no incluyen los encabezados de 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 misma URL de extremo y los mismos 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 la implementación de un proxy de API para ayudar a administrar el volumen de solicitudes que tu agente puede enviar a tu proveedor de OAuth externo.

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 que otorgues el rol de Cloud Run Invoker (roles/run.invoker) a

[e-mail]

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 ningún parámetro 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 del 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 bibliotecas cliente de Google o 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 del 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 se les otorga 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 para 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 tu política de la organización lo permita. 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 Usuario con 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 secreto y pega tu credencial como el valor del secreto:
   • 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 salto de línea 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. Configura los parámetros de autenticación:
   • Si usas encabezados de autenticación, crea un nuevo encabezado de la solicitud de versión del secreto. Ingresa "Authorization" en el campo Clave y pega el nombre de la versión secreta en el campo Versión secreta.
   • Para la autenticación básica con 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 secreto en OAuth de terceros y pega el nombre de la versión del secreto en el campo Versión del secreto.
8. Haz clic en Guardar.

Nota: Solo admitimos secretos globales de Secret Manager. No admitimos los 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 deseas 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 CA 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 tu webhook antes de implementarlas en producción.

Crear o editar recursos de webhook

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

Para crear o editar un recurso de webhook, haz lo siguiente:

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 estándar del recurso de webhook o los parámetros de configuración flexibles del recurso de webhook.
8. Haz clic en Guardar.

API

Para obtener información sobre cómo crear un recurso de webhook, consulta el método create del 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 para 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 del entorno	Recurso del 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 mostrar 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: Servicio no disponible

En las siguientes situaciones de error, Dialogflow CX invoca un error de webhook o un evento integrado de tiempo de espera y continúa el procesamiento de manera habitual:

• Se excedió 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 detección de intent, el campo queryResult.webhookStatuses en la respuesta de detección de intent contiene la información del 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 las fallas transitorias, como los tiempos de espera de solicitudes, las conexiones de red interrumpidas y los códigos de estado HTTP en el rango 5xx (como 500 Server fault o 503 Service unavailable). Los errores terminales del cliente, como el código de estado HTTP 404 Not found, fallan de inmediato sin reintentos.

Latencia acumulativa y presupuesto de tiempo de espera

Dado que Dialogflow CX reintenta los errores transitorios 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 muestre un error. Por ejemplo, con el parámetro de configuración predeterminado de tiempo de espera de 5 segundos, un endpoint que no responde agota el tiempo de espera después de 5 segundos en el intento inicial y agota el tiempo de espera 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 upstream (como los sistemas de telefonía o de respuesta de voz interactiva [IVR] que finalizan las llamadas después de un período de espera de 10 segundos), asigna un presupuesto para ambos intentos configurando el tiempo de espera del webhook en la mitad del período permitido (por ejemplo, entre 2.5 y 4 segundos).

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 de tu 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 webhooks de Dialogflow CX. Se recomienda mantener seguros tus recursos. 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 con 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 Service Agent Auth y, luego, token de ID en la configuración de autenticación para que tu agente pueda llamar de forma segura a tu webhook.

Debes configurar manualmente esta integración en las siguientes dos situaciones:

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

   [e-mail]

   Esta cuenta de servicio especial y la clave asociada se suelen crear 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 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 el proyecto de tu recurso de Cloud Run.

A continuación, selecciona Service Agent Auth > ID Token en la sección Configuración de autenticación.

Usa webhooks alojados en contenedores y el framework de Go ezcx

Para implementar un webhook 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 con tráfico solo 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 de redes de nube privada virtual (VPC) en el mismo proyecto o el mismo perímetro de Controles del servicio de VPC como un webhook, siempre que el agente se encuentre en el mismo proyecto o el mismo perímetro de Controles del servicio de VPC.

Usa el Directorio de servicios para acceder a redes privadas

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

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

1. Sigue las instrucciones de 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 de 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. Debe existir la cuenta de servicio del Agente de servicio de Dialogflow CX con la siguiente dirección para tu proyecto de agente:

   [e-mail]

   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 está en un proyecto diferente al 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. Cuando crees el webhook, especifica el servicio del Directorio de servicios, la URL y cualquier información de autenticación opcional.

   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 y verificar 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.