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

Authentication

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:

Verificación de certificado HTTPS

Dialogflow usa de forma predeterminada 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, consulta lo siguiente:Certificados de CA personalizados ,

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(V3) o WebhookRequest(V3Beta1) para obtener más detalles.

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(V3) o WebhookResponse(V3Beta1) para obtener más detalles.

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 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 las siguientes funciones 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# 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

Ejemplos

En los siguientes ejemplos, se muestra cómo recibir una WebhookRequest y enviar una WebhookResponse.

Java


// TODO: add GSON dependency to Pom file
// (https://mvnrepository.com/artifact/com.google.code.gson/gson/2.8.5)
// TODO: Uncomment the line bellow before running cloud function
// package com.example;

import com.google.cloud.functions.HttpFunction;
import com.google.cloud.functions.HttpRequest;
import com.google.cloud.functions.HttpResponse;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;
import java.io.BufferedWriter;

public class Example implements HttpFunction {

  public void service(HttpRequest request, HttpResponse response) throws Exception {
    JsonParser parser = new JsonParser();
    Gson gson = new GsonBuilder().create();

    JsonObject job = gson.fromJson(request.getReader(), JsonObject.class);
    String str = job.getAsJsonObject("fulfillmentInfo").getAsJsonPrimitive("tag").toString();
    JsonObject o = null;
    String a = '"' + "Default Welcome Intent" + '"';
    String b = '"' + "get-agent-name" + '"';
    String responseText = "";

    if (str.equals(a)) {
      responseText = '"' + "Hello from a Java GCF Webhook" + '"';
    } else if (str.equals(b)) {
      responseText = '"' + "My name is Flowhook" + '"';
    } else {
      responseText = '"' + "Sorry I didn't get that" + '"';
    }

    o =
        parser
            .parse(
                "{ \"fulfillment_response\": { \"messages\": [ { \"text\": { \"text\": ["
                    + responseText
                    + "] } } ] } }")
            .getAsJsonObject();
    BufferedWriter writer = response.getWriter();
    writer.write(o.toString());
  }
}

Node.js


// TODO: change entry point to exports.handleWebhook in cloud function

exports.handleWebhook = (request, response) => {
  const tag = request.body.fulfillmentInfo.tag;
  let text = '';

  if (tag === 'Default Welcome Intent') {
    text = 'Hello from a GCF Webhook';
  } else if (tag === 'get-name') {
    text = 'My name is Flowhook';
  } else {
    text = `There are no fulfillment responses defined for "${tag}"" tag`;
  }

  const jsonResponse = {
    fulfillment_response: {
      messages: [
        {
          text: {
            //fulfillment text response to be sent to the agent
            text: [text],
          },
        },
      ],
    },
  };

  response.send(jsonResponse);
};

Python


# TODO(developer): change entry point to handle_webhook in cloud function

def handle_webhook(request):

    req = request.get_json()

    tag = req["fulfillmentInfo"]["tag"]

    if tag == "Default Welcome Intent":
        # You can also use the google.cloud.dialogflowcx_v3.types.WebhookRequest protos instead of manually writing the json object
        # Please see https://googleapis.dev/python/dialogflow/latest/dialogflow_v2/types.html?highlight=webhookresponse#google.cloud.dialogflow_v2.types.WebhookResponse for an overview
        res = {
            "fulfillment_response": {
                "messages": [{"text": {"text": ["Hi from a GCF Webhook"]}}]
            }
        }
    elif tag == "get-name":
        res = {
            "fulfillment_response": {
                "messages": [{"text": {"text": ["My name is Phlowhook"]}}]
            }
        }
    else:
        res = {
            "fulfillment_response": {
                "messages": [
                    {
                        "text": {
                            "text": [
                                f"There are no fulfillment responses defined for {tag} tag"
                            ]
                        }
                    }
                ]
            }
        }

    # Returns json
    return res