Webhooks

Los webhooks son servicios que alojan la 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 a fin de generar respuestas dinámicas, validar datos recopilados o activar acciones en el backend.

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

Webhooks estándar

Con los webhooks estándar, puedes usar mensajes de solicitud y respuesta definidos por Dialogflow. 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 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 ID de llamada 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 de recursos de webhook estándar

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

Período Definición
Nombre visible Es el nombre que se muestra en la consola para el webhook.
Tiempo de espera de webhook Cuando Dialogflow envía una solicitud de webhook a tu servicio de webhook, es posible que se agote el tiempo de espera mientras se espera una respuesta. Esta configuración controla el tiempo de espera en segundos. Si se agota el tiempo de espera, Dialogflow invoca un evento webhook.error.timeout.
Tipo Configúralo como Directorio de servicios si usas el directorio de servicios para el acceso a una red privada; de lo contrario, establécelo como 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 la AC personalizado Se usa para subir certificados de CA personalizados.

Webhooks flexibles

Con los webhooks flexibles, tú 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. Esta limitación es en realidad beneficiosa, porque simplifica la interfaz entre el agente y el webhook. Rara vez se necesita comunicar algo que no sean valores de parámetros de sesión entre un agente y un webhook. También simplifica la implementación de 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 creas el recurso de webhook para tu agente, puedes especificar lo siguiente para las solicitudes de webhook:

  • El método HTTP que se usa para las solicitudes de webhook que se envían a tu servicio de webhook.
  • Valores de parámetros de sesión que Dialogflow debe enviar a tu servicio de webhook mediante la URL.
  • Si eliges POST, PUT o PATCH como el método, puedes especificar valores de parámetros de sesión que Dialogflow debe enviar a tu servicio de webhook a través del cuerpo JSON de la solicitud.

Para enviar valores de parámetros de sesión mediante la URL de la solicitud o el cuerpo JSON, usa las referencias del parámetro como lo harías normalmente. No es necesario que escapes de URL de la referencia del parámetro ni que la encierres entre comillas. En el entorno de ejecución, Dialogflow escapará el valor del parámetro según sea necesario. Se proporcionará una lista o un valor compuesto en formato JSON.

Cuando usas una referencia de parámetro en el cuerpo JSON, debes encerrar la referencia entre comillas, sin importar el tipo de parámetro. Si el parámetro es en realidad un valor escalar numérico, de lista o compuesto, Dialogflow 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 string permanecerán entre comillas. Si se hace referencia a un valor numérico escalar, de lista o compuesto dentro de un valor de string (por ejemplo: “This is a number: $session.params.size”), el parámetro se tratará como una string (“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, para el 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 parámetros de sesión que Dialogflow debe establecer en campos específicos de la respuesta de webhook en el entorno 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 "valor", usa lo siguiente:

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

Configuración de recursos de webhooks flexibles

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

Período Definición
Nombre visible Es el nombre que se muestra en la consola para el webhook.
Tiempo de espera de webhook Cuando Dialogflow envía una solicitud de webhook a tu servicio de webhook, es posible que se agote el tiempo de espera mientras se espera una respuesta. Esta configuración controla el tiempo de espera en segundos. Si se agota el tiempo de espera, Dialogflow invoca un evento webhook.error.timeout.
Tipo Configúralo como Directorio de servicios si usas el directorio de servicios para el acceso a una red privada; de lo contrario, establécelo como Servicio web genérico.
URL de webhook Proporciona la dirección URL de tu servicio de webhook, que puede incluir referencias a los parámetros de sesión.
Subtipo Configurar como Flexible
Método Configura 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 respuesta Proporciona los parámetros de sesión que se deben configurar 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.

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 Dialogflow estén autorizados a realizar solicitudes. Esto se configura cuando se crea un recurso de webhook. Dialogflow CX admite los siguientes mecanismos de autenticación:

Período Definición
Encabezados de autenticación Para la configuración de webhook, puedes especificar pares clave-valor de encabezado HTTP opcionales. Si se proporciona, Dialogflow agrega estos encabezados HTTP a las solicitudes de webhook. Es común proporcionar un solo par con una clave de authorization. Los valores del encabezado admiten referencias de parámetros de sesión y el análisis de funciones del sistema, como en los mensajes de respuesta estática.
Autenticación básica con nombre de usuario y contraseña Para la configuración del webhook, puedes especificar los valores opcionales de nombre de usuario y contraseña de acceso. Si se proporciona, Dialogflow 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>".
OAuth de terceros Puedes especificar la configuración de OAuth de terceros para que Dialogflow intercambie un token de acceso del proveedor de OAuth y lo agregue al 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 en 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 del agente de servicio para la autenticación. Se puede usar para acceder a los servicios de Cloud Function y Cloud Run. Si no se usan otras opciones de autenticación, esta opción estará habilitada de forma predeterminada.
Autenticación mutua de TLS Consulta la documentación sobre la autenticación mutua de TLS.

Verificación de certificados HTTPS

Dialogflow 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 sistemas de producción de sistemas de desarrollo (recomendado), puedes configurar tus webhooks para que sean específicos del entorno. En cada recurso de webhook que definas, puedes proporcionar una configuración de URL y autenticación única para cada entorno que hayas definido para el agente.

Esto 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

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

Con el fin de 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
Rita No disponible No disponible

Si quieres editar la configuración específica del entorno para 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 de entorno Recurso de entorno
RPC Interfaz de entorno Interfaz de 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
Rita 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, Dialogflow 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.

Usa Cloud Functions

Dialogflow se integra a Cloud Functions, 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, tu agente puede llamar de forma segura a tu webhook sin necesidad de realizar una configuración especial.

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 Dialogflow 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 la Función de IAM del Invocador de Cloud Functions a la cuenta de servicio del Agente de servicio de Dialogflow en el proyecto de la función.

Usa webhooks alojados en contenedores y el framework Go ezcx

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

Usa el Directorio de servicios para acceder a redes privadas

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

  2. Debe existir la cuenta de servicio del Agente de servicio de Dialogflow 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 Dialogflow 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
    Rita No disponible No disponible

Para solucionar problemas, puedes configurar una verificación de tiempo de actividad privada a fin de comprobar que el Directorio de servicios esté configurado de forma correcta.

Autenticación del agente de servicio

Dialogflow puede generar un token de ID o un token de acceso mediante el agente de servicio de Dialogflow.

El token se agrega en el encabezado HTTP de autorización cuando Dialogflow llama a un webhook.

Token de ID

Se puede usar un token de ID para acceder a los servicios de Cloud Function y Cloud Run después de que otorgues el rol de Invocador a

service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
Si los servicios de Cloud Function y Cloud Run están en el mismo proyecto de recursos, no necesitas permiso de IAM adicional para llamarlos.

De manera opcional, cualquier webhook puede validar el token mediante bibliotecas cliente de Google o bibliotecas de código abierto como github.com/googleapis/google-auth-library-nodejs.

Token de acceso

Puedes usar un token de acceso para acceder a otras APIs de Google Cloud después de que otorgues los roles necesarios a

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

Ejemplos y solución de problemas

Consulta la guía práctica de webhook.