Webhooks

Los webhooks son servicios que alojan la lógica empresarial. 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.

Los webhooks de CX son similares a los webhooks de ES, excepto que los campos de solicitud y respuesta se cambiaron para admitir características de CX.

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.
  • Debe administrar las solicitudes POST con un cuerpo JSON WebhookRequest.
  • Debe responder a las solicitudes WebhookRequest con un cuerpo JSON WebhookResponse.

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:

Solicitud de webhook

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 con información sobre el intent que coincide.

Consulta la documentación de referencia de WebhookRequest para obtener más información.

Respuesta de webhook

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 para obtener más información.

Crea un recurso 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. Para crear un recurso de webhook, haz lo siguiente:

Console

  1. Abre la consola de Dialogflow CX.
  2. Elige tu proyecto de GCP.
  3. Selecciona el agente.
  4. Selecciona la pestaña Administrar.
  5. Haz clic en Webhooks.
  6. Haga clic en Crear.
  7. Ingresa los datos de webhook.
  8. Haga clic en Save.

API

Consulta el método create 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# No disponible No disponible
Go No disponible No disponible
Java WebhooksClient WebhooksClient
Node.js WebhooksClient WebhooksClient
PHP No disponible No disponible
Python WebhooksClient WebhooksClient
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, 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 el Directorio de servicios para el acceso privado a redes

Dialogflow se integra con el acceso a la red privada del Directorio de servicios para que pueda 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 orientado a una red privada, sigue estos pasos:

  1. Sigue la 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 las siguientes funciones de IAM:
    • servicedirectory.viewer del proyecto del Directorio de servicios
    • servicedirectory.pscAuthorizedService del proyecto de red
  3. Proporciona el servicio del Directorio de servicios junto con la URL y la información de autenticación opcional cuando crees el webhook.

    Console

    Captura de pantalla de webhook de 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# No disponible No disponible
    Go No disponible No disponible
    Java WebhooksClient WebhooksClient
    Node.js WebhooksClient WebhooksClient
    PHP No disponible No disponible
    Python WebhooksClient WebhooksClient
    Ruby No disponible No disponible

Tokens de identidad del servicio

Cuando Dialogflow llama a un webhook, proporciona un token de identidad de Google con la solicitud. Cualquier webhook 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. Por ejemplo, puedes verificar el email del token de ID de la siguiente manera:

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