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 los agentes de conversación (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, los agentes conversacionales (Dialogflow CX) definen los campos de solicitud y respuesta. 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 los agentes conversacionales (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:

Término Definición
Nombre visible Es el nombre que se muestra en la consola para el webhook.
Tiempo de espera del webhook Cuando los agentes conversacionales (Dialogflow CX) envían una solicitud de webhook a tu servicio de webhook, es posible que se agote el tiempo de espera mientras espera una respuesta. Este parámetro de configuración controla ese tiempo de espera en segundos. Si se produce un tiempo de espera, los agentes conversacionales (Dialogflow CX) invocan un evento webhook.error.timeout.
Tipo Establece Directorio de servicios si usas el directorio de servicios para acceder a redes privadas. De lo contrario, establece 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 de autenticación.
Certificado de AC personalizado Se usa para subir certificados de AC personalizados.

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.
  • Son los valores de los parámetros de sesión que los agentes conversacionales (Dialogflow CX) deben 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. Durante el tiempo de ejecución, Agentes conversacionales (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 de la solicitud JSON, 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:

Término Definición
Nombre visible Es el nombre que se muestra en la consola para el webhook.
Tiempo de espera del webhook Cuando los agentes conversacionales (Dialogflow CX) envían una solicitud de webhook a tu servicio de webhook, es posible que se agote el tiempo de espera mientras espera una respuesta. Este parámetro de configuración controla ese tiempo de espera en segundos. Si se produce un tiempo de espera, los agentes conversacionales (Dialogflow CX) invocan un evento webhook.error.timeout.
Tipo Establece Directorio de servicios si usas el directorio de servicios para acceder a redes privadas. De lo contrario, establece 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 Establece la opción en Flexible.
Método Establece el método HTTP para la solicitud delwebhook.
Cuerpo de la solicitud Proporciona el cuerpo JSON de la solicitud como se describió anteriormente.
Configuración de respuestas 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 AC personalizado Se usa para subir certificados de AC personalizados.

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:

Autenticación

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

Término Definición
Encabezados de autenticación Para la configuración del webhook, puedes especificar pares clave-valor de encabezado HTTP opcionales. Si se proporcionan, los agentes conversacionales (Dialogflow CX) agregan 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.
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, los agentes de conversación (Dialogflow CX) agregan 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>".
OAuth de terceros Puedes especificar la configuración de OAuth de terceros para que los agentes conversacionales (Dialogflow CX) intercambien un token de acceso del sistema de OAuth y lo agreguen en el encabezado HTTP de autorización. Solo se admite el flujo de credenciales de cliente.
Tokens de acceso del agente de servicio Puedes seleccionar el token de acceso en la autenticación del agente de servicio para usar tokens de acceso del agente 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 seleccionar el token de ID en la autenticación del agente de servicio para usar tokens de ID de agente de servicio para la autenticación. Se puede usar para acceder a las funciones y los servicios de Cloud Run.
Autenticación mutua de TLS Consulta la documentación de autenticación TLS mutua.

OAuth de terceros

Los agentes conversacionales (Dialogflow CX) pueden recopilar un token de acceso de un proveedor de OAuth externo y agregarlo al encabezado HTTP de autorización cuando realizan sus solicitudes de webhook.

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

Término Definición
ID de cliente Es el ID de cliente que se usará cuando se solicite un token de OAuth.
Secreto del cliente El secreto que se usará cuando se solicite un token de OAuth.
URL del extremo de OAuth 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 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

Los agentes conversacionales (Dialogflow CX) pueden generar un token de ID o un token de acceso con el agente de servicio de agentes conversacionales (Dialogflow CX).

El token se agrega en el encabezado HTTP de autorización cuando los agentes de conversación (Dialogflow CX) llaman 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
Si las funciones y los servicios de Cloud Run se encuentran en el mismo proyecto de recursos, no necesitas permisos de IAM adicionales para llamarlos.

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

Verificación de certificados HTTPS

Los agentes conversacionales (Dialogflow CX) usan 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 tuwebhook 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:

Console

  1. Abre la consola de Dialogflow CX.
  2. Elige tu proyecto de Google Cloud.
  3. Selecciona el agente.
  4. Selecciona la pestaña Administrar.
  5. Haz clic en Webhooks.
  6. Haz clic en Crear o en un recurso de webhook de la lista para editarlo.
  7. Ingresa la configuración de recursos de webhook estándar o la configuración de recursos de webhook flexible.
  8. Haz clic en Guardar.

API

Para crear un recurso de webhook, consulta el método create para el tipo Webhook. Para editar un recurso de webhook (excepto la configuración específica del entorno), consulta el método patch o update para el tipo 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

Para editar la configuración específica del entorno de un webhook, consulta el método patch o update para el tipo Environment.

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

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

Los agentes conversacionales (Dialogflow CX) incluyen mecanismos internos que vuelven a intentarlo automáticamente en 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

Los agentes conversacionales (Dialogflow CX) se integran 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 de conversación (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 la 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 (Dialogflow CX) 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 de conversación (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

    Captura de pantalla de webhook del Directorio de servicios.

    API

    Consulta el campo serviceDirectory para el tipo 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

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.