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 Conversational Agents (Dialogflow CX) para generar respuestas dinámicas, validar los 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 de conversación (Dialogflow CX) definen los campos de solicitud y respuesta. Con un webhook flexible, defines los campos de solicitud y respuesta.

Webhooks estándar

Con webhooks estándar, Cuando uses mensajes de solicitud y respuesta definidos por los agentes de conversación (Dialogflow CX). El mensaje de solicitud proporciona muchos detalles sobre la sesión. Por ejemplo, página activa actual, 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 un elemento entrega con un webhook, Los Conversational Agents (Dialogflow CX) envían una solicitud de webhook POST HTTPS a tu servicio de webhook. El cuerpo de esta solicitud es un objeto JSON WebhookRequest con información sobre la sesión.

Algunos integraciones Propaga el campo WebhookRequest.payload con información adicional. Por ejemplo, el Integración de Dialogflow CX Phone Gateway 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 El nombre que se muestra en la consola para el webhook.
Tiempo de espera de 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. Esta configuración controla ese tiempo de espera en segundos. Si se agota el tiempo de espera, los agentes de conversación (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 Debe establecerse 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 la AC personalizados.

Webhooks flexibles

Con webhooks flexibles, defines el método de solicitud HTTP, los parámetros de la URL de solicitud y 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. Rara vez se necesita comunicar algo 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 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 enviados 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 el método, puedes especificar los valores de los parámetros de sesión que los agentes de conversación (Dialogflow CX) pueden usar se 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 escape de la URL de la referencia del parámetro. y no debes poner la referencia entre comillas. Durante el tiempo de ejecución, los agentes conversacionales (Dialogflow CX) escaparán 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 escalares de strings permanecerán entre comillas. Si se hace referencia a un valor numérico escalar, de lista o compuesto en 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 del parámetro 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
          }
        }
      ]
    }
  ]
}

Especificar el "valor" campo, 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 El nombre que se muestra en la consola para el webhook.
Tiempo de espera de webhook Cuando Conversational Agents (Dialogflow CX) 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. 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 Proporcione la dirección URL de su servicio de webhook, que puede incluir referencias a parámetros de sesión.
Subtipo Configúralo 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 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 AC personalizado Se usa para subir certificados de la AC personalizados.

Usa una plantilla personalizada predefinida

Dialogflow ofrece plantillas personalizadas predefinidas que puedes usar para integrar webhooks flexibles con la 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 para la API. La plantilla complete automáticamente el formulario de webhook según el nombre de la API que elegir.

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

      • URL de webhook
      • Método
      • JSON del cuerpo de la solicitud
      • Configuración de respuesta
    2. Los campos obligatorios de OAuth se destacarán en Authentication secció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 Conversational Agents (Dialogflow CX) estén autorizados a realizar solicitudes. Esto se configura cuando se crea un recurso de webhook. Los agentes de conversación (Dialogflow CX) admiten los siguientes mecanismos de autenticación:

Término Definición
Encabezados de autenticación Para la configuración de webhook, puedes especificar pares clave-valor del encabezado HTTP opcionales. Si se proporcionan, los agentes de conversación (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 proporcionan, Conversational Agents (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>".
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. Puede usarse para acceder a las funciones y los servicios de Cloud Run.
Autenticación mutua de TLS Consulta la documentación de Autenticación mutua de TLS.

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 El ID de cliente que se debe usar cuando se solicita 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 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 en la cadena de consulta de la URL del extremo de OAuth.

Tokens de acceso del agente de servicio

Los agentes de conversación (Dialogflow CX) pueden generar un Token de ID o token de acceso mediante Agente de servicio de agentes de conversación (Dialogflow CX).

El token se agrega al 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 están en el mismo proyecto de recursos, no necesitas recursos permiso de IAM 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 de conversación (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 única y parámetros de configuración de autenticación de cada entorno que hayas definido para el agente.

Esto te permite desarrollar y probar de forma segura las actualizaciones del 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:

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 flexible de recursos de webhook.
  8. Haz clic en Guardar.

API

Si deseas crear un recurso de webhook, consulta el método create para el tipo Webhook. Para editar un recurso de webhook (excepto para la configuración específica del entorno), haz lo siguiente: 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 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
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, Los agentes de conversación (Dialogflow CX) invocan un error o tiempo de espera de webhook integrado y continúa el procesamiento como de costumbre:

  • 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 de conversación (Dialogflow CX) incluyen mecanismos internos que reintentan 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, sigue estos pasos:

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

Usa funciones de Cloud Run

Los agentes de conversación (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 -> de ID en la configuración de Auth. tu agente puede llamar de forma segura a tu webhook.

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

  1. El agente de servicio de Conversational Agents (Dialogflow CX) cuenta de servicio Debe existir 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 -> Token de ID en la sección Auth configuration.

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 un 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 un verificación de tiempo de actividad privada para comprobar que tu Directorio de servicios esté configurado correctamente.

Ejemplos y solución de problemas

Consulta la guía práctica de webhooks.