Webhooks

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Un webhook puede ser un webhook estándar o un webhook flexible. Con un webhook estándar, los campos de solicitud y respuesta los definen los agentes conversacionales (Dialogflow CX). Con un webhook flexible, defines los campos de solicitud y respuesta.

Webhooks estándar

Con los webhooks estándar, usas los mensajes de solicitud y respuesta definidos por Conversational Agents (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, los agentes conversacionales (Dialogflow CX) envían 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.

Consulta la documentación de referencia de WebhookRequest(V3) o WebhookRequest(V3Beta1) para obtener más detalles.

Respuesta de webhook estándar

Cuando tu servicio de webhook recibe una solicitud de webhook, necesita enviar una respuesta de webhook. Se aplican las siguientes limitaciones a tu respuesta:

• La respuesta debe ocurrir dentro del tiempo de espera que configures 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 menor o igual que 64 KiB.

Consulta la documentación de referencia de WebhookResponse(V3) o WebhookResponse(V3Beta1) para obtener más detalles.

Configuración estándar de recursos de webhook

A continuación, se describe la configuración de recursos de webhook para los webhooks estándares:

Webhooks flexibles

Con 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. Esta limitación es beneficiosa, ya que simplifica la interfaz entre el agente y el webhook. En general, no es necesario comunicar nada más que los valores de los parámetros de sesión entre un agente y un webhook. 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 varias 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.
• Valores de los parámetros de sesión que Conversational Agents (Dialogflow CX) debe enviar a tu servicio de webhook con la URL.
• Si eliges POST, PUT o PATCH como método, puedes especificar los valores de los parámetros de sesión que los agentes conversacionales (Dialogflow CX) deben enviar a tu servicio de webhook a través del cuerpo JSON de la solicitud.

Para enviar valores de parámetros de sesión con la URL de la solicitud o el cuerpo JSON, usa referencias de parámetros como lo harías normalmente. No es necesario que escapes la referencia del parámetro con una URL ni que la encierres entre comillas. En el tiempo de ejecución, Conversational Agents (Dialogflow CX) escapará el valor del parámetro como sea necesario. Se proporcionará una lista o un valor compuesto como JSON.

Cuando uses una referencia de parámetro en el cuerpo JSON, debes encerrar 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, los agentes conversacionales (Dialogflow CX) quitarán las comillas cuando envíen la solicitud en el tiempo de ejecución para preservar el tipo de datos del parámetro. Los tipos de 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 flexible del webhook

Cuando crees el recurso de webhook para tu agente, puedes especificar los parámetros de sesión que los agentes de conversación (Dialogflow CX) deben establecer en campos específicos de la respuesta del webhook durante el tiempo de ejecución.

Se aplican las siguientes limitaciones a tu respuesta:

• La respuesta debe ocurrir dentro del tiempo de espera que configures 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 menor o igual que 64 KiB.

Usa el siguiente formato para especificar un campo escalar, de lista o compuesto:

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

A continuación, se describe la configuración de recursos de webhook para webhooks flexibles:

Usa una plantilla personalizada predefinida

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

1. En la pestaña Administrar, haz clic en Webhooks y, luego, en + Crear.

2. En Subtipo, selecciona Flexible.

3. Haz clic en Configurar con una plantilla predefinida para habilitar la función.

4. En el menú desplegable Tipo de integración, selecciona Salesforce.

5. En el menú desplegable Nombre de la API, selecciona un nombre de API. La plantilla completa automáticamente el formulario delwebhook según el nombre de la API que elijas.

   1. Si corresponde, puedes configurar manualmente los siguientes campos según tus parámetros:

      • URL de webhook
      • Método
      • Cuerpo JSON 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 para crear el webhook.

Requisitos del servicio de webhook

El servicio de webhook debe cumplir con los siguientes requisitos:

• Debe administrar solicitudes HTTPS. HTTP no es compatible. Si alojas tu servicio de webhook en Google Cloud Platform mediante una solución de Compute o de procesamiento sin servidores, consulta la documentación del producto para la entrega con HTTPS. A fin de conocer otras opciones de hosting, consulta Obtén un certificado SSL para el dominio.
• La URL para las solicitudes debe ser de acceso público, a menos que se aloje como una función de Cloud Run o se acceda a ella como un webhook del Directorio de servicios.
• Debe controlar 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. Consulta el Directorio de servicios para obtener más información.

Autenticación

Es importante proteger el servicio de webhook para que solo tú o tu agente de Conversational Agents (Dialogflow CX) estén autorizados a realizar solicitudes. Esto se configura cuando se crea un recurso de webhook. Conversational Agents (Dialogflow CX) admite los siguientes mecanismos de autenticación:

OAuth de terceros

Conversational Agents (Dialogflow CX) puede recopilar un token de acceso de un proveedor de OAuth externo y agregarlo al encabezado HTTP de autorización cuando realiza sus solicitudes de webhook.

A continuación, se describe la configuración de recursos para OAuth de terceros:

Las solicitudes que se envían 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.

Tokens de acceso del agente de servicio

Conversational Agents (Dialogflow CX) puede generar un token de ID o un token de acceso con el agente de servicio de Conversational Agents (Dialogflow CX).

El token se agrega en el encabezado HTTP de autorización cuando Conversational Agents (Dialogflow CX) llama a un webhook.

Token de ID

Se puede usar un token de ID para acceder a las funciones y los servicios de Cloud Run después de otorgar el rol de invocador a

service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com

El público que se use para generar el token de ID será la URL completa del webhook, excepto los parámetros de consulta. Si usas Cloud Run, asegúrate de que los públicos de Cloud Run admitan esta URL. Por ejemplo, si la URL del webhook es

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 de manera opcional el token con bibliotecas cliente de Google o bibliotecas de código abierto como github.com/googleapis/google-auth-library-nodejs.

Token de acceso

Un token de acceso se puede usar para acceder a otras APIs de Google Cloud después de otorgar los roles necesarios a

service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com

Cuenta de servicio

Las cuentas de servicio se pueden usar para autenticar solicitudes de webhook a cualquier API de Google que las admita. 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 lo harías con cualquier otra principal. El correo electrónico de la cuenta de servicio se usará para generar un token de acceso, que se enviará en el encabezado Authorization de la solicitud del webhook.

Para usar esta función, se requieren los siguientes permisos:

• roles/iam.serviceAccountUser al usuario que crea o actualiza el webhook para usar la autenticación de la cuenta de servicio.
• roles/iam.serviceAccountTokenCreator al agente de servicio de Dialogflow.

Si intentas usar cuentas de servicio en varios proyectos, asegúrate de que la política de la organización las admita. Se deben otorgar ambos permisos 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 secretos con Secret Manager. Estos son los pasos necesarios para autenticar tu webhook con secretos:

1. Crea tu secreto si aún 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 nueva versión del secreto a tu secreto. 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 con 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 acabas de agregar. El formato del nombre es projects/{project_id}/secrets/{secret_id}/versions/{version_id}".
6. Abre la pantalla de edición del webhook y, luego, haz lo siguiente:
   • Si usas encabezados de autenticación, crea un nuevo encabezado de solicitud de versión secreta. Ingresa "Authorization" como Clave y pega el nombre de la versión secreta en el cuadro de entrada Versión secreta.
   • Si usas la autenticación básica con nombre de usuario y contraseña, haz clic en Versión secreta en Autenticación básica y pega el nombre de la versión secreta en el cuadro de entrada Versión secreta.
   • Si usas OAuth de terceros, haz clic en Versión secreta en OAuth de terceros y pega el nombre de la versión secreta en el cuadro de entrada Versión secreta.
7. Haz clic en Guardar.

Verificación de certificados HTTPS

Conversational Agents (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, consultaCertificados de CA personalizados.

Webhooks específicos del entorno

Si usas entornos para aislar los sistemas de producción de los sistemas de desarrollo (recomendado), puedes configurar tus webhooks para que sean específicos del entorno. Para cada recurso de webhook que definas, puedes proporcionar una URL y una configuración de autenticación únicas para cada entorno que hayas definido para el agente.

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

Crea o edita recursos de webhook

Una vez que tengas en ejecución un servicio de webhook, debes crear un recurso de webhook en tu agente que tenga información sobre la conectividad y la autenticación. Después de la creación, también puedes editar la configuración del recurso de webhook en cualquier momento.

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

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 Prohibido
• 404 No encontrado
• 500 Falla del servidor
• 503 Servicio no disponible

En cualquiera de las siguientes situaciones de error, Agentes conversacionales (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 respuesta
• Código de estado de error recibido
• La respuesta no es válida
• El servicio de webhook no está disponible

Además, si la llamada al servicio de webhook se activó mediante una llamada a la API de detección de intents, el campo queryResult.webhookStatuses en la respuesta de detección de intent contiene la información del estado del webhook.

Reintentos automáticos

Conversational Agents (Dialogflow CX) incluye mecanismos internos que vuelven a intentar automáticamente ciertos errores de webhook para mejorar la solidez. Solo se vuelven a intentar los errores no terminales (por ejemplo, errores de tiempo de espera o de conexión).

Para reducir la probabilidad de llamadas duplicadas, haz lo siguiente:

• Establece umbrales de tiempo de espera de webhook más largos.
• Admite la idempotencia en la lógica del webhook o anula la duplicación.

Usa funciones de Cloud Run

Conversational Agents (Dialogflow CX) se integra a las funciones de Cloud Run, por lo que puedes crear fácilmente un webhook seguro y sin servidores. Si creas una función que reside en el mismo proyecto que tu agente, solo debes seleccionar Service Agent Auth -> ID Token en la configuración de Auth. Luego, tu agente podrá llamar de forma segura a tu webhook.

Sin embargo, hay dos situaciones en las que debes configurar manualmente esta integración:

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

   service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com

   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 del Invocador de Cloud Functions a la cuenta de servicio del Agente de servicio de agentes conversacionales (CX de Dialogflow) en el proyecto de tu función.
3. Selecciona Service Agent Auth -> ID Token en la sección de configuración de Auth.

Usa webhooks alojados en contenedores y el framework ezcx de Go

Si deseas implementar un webhook alojado en contenedores con Go, consulta el framework ezcx de Go. Este framework puede simplificar muchos de los pasos necesarios para crear un webhook.

Usa funciones de Cloud Run con tráfico solo interno

Las funciones de Cloud Run configuradas para aceptar tráfico interno de redes de VPC en el mismo proyecto o el mismo perímetro de VPC SC se pueden usar como webhook, siempre que el agente esté en el mismo proyecto o el mismo perímetro de VPC SC.

Usa el Directorio de servicios para acceder a redes privadas

Los agentes conversacionales (CX de Dialogflow) se integran al acceso a la red privada del Directorio de servicios, por lo que pueden 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 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.

2. Debe existir la cuenta de servicio del Agente de servicio de agentes conversacionales (Dialogflow CX) con la siguiente dirección para tu proyecto de agente:

   service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com

   Otorga a la cuenta de servicio del agente de servicio de agentes conversacionales (Dialogflow CX) los siguientes roles de IAM:
   • servicedirectory.viewer del proyecto del Directorio de servicios
   • servicedirectory.pscAuthorizedService del proyecto de red

3. Cuando crees el webhook, proporciona el servicio del Directorio de servicios junto con la URL y la 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 para verificar que tu Directorio de servicios esté configurado correctamente.

Muestras y solución de problemas

Consulta la guía práctica de webhooks.