Webhooks

Los webhooks son activadores automatizados iniciados entre dos aplicaciones ante la ocurrencia de un evento predefinido. En nuestro caso, si eliges tener tu lógica de negocio en cualquier servidor externo, puedes optar por webhooks como la plataforma de desarrollo. Debes asegurarte de que el servidor externo sea accesible públicamente para ConvoKraft a través de una API REST. Para ejecutar la lógica de negocio, la URL del Webhook configurada será invocada por ConvoKraft en los puntos de invocación correspondientes durante la ejecución de la acción.

El servidor de Webhook debe cumplir con los siguientes formatos de solicitud y respuesta para el funcionamiento correcto del bot de ConvoKraft.

Formato de Solicitud

ConvoKraft envía la solicitud en el siguiente formato a la URL de Webhook configurada.

{
"todo": "prompt || execute || fallback || button",
"bot" : "",
"action" : "",
"button_id" : "",
"environment" : "development || production"
"params":{
},
"userInput" : "",
"previousParam" : "",
"user" : {},
"org" : {},
"broadcast" : {},
"cache" : {},
"sessionData" : {}
"clientData" : {} 
}

Formato de Respuesta

ConvoKraft espera que la respuesta esté en el siguiente formato desde la URL del Webhook, para que pueda comprender y transmitir la respuesta prevista al usuario. ConvoKraft soporta múltiples tipos de respuesta para mostrar contenido en diversos formatos. Debes asegurarte de seguir los estándares definidos al configurar las respuestas. Para más información sobre las estructuras de respuesta, consulta esta sección.

Caso 1: Cuando se debe solicitar un parámetro de entrada al usuario

{
"status" : "prompt",
    "prompt" : {
        "param_name" : "leave_type",
        "options":[  
                    { "id" : "111" ,"label" : "", "image" : "image_url"},
                    {"id" : "112" ,"label" :"" ,"image" : "image_url"}
        ],
"buttons" : []
    },
    "message" : "You don't have enough casual leaves. Please choose some other leave type.",
    "data" : {}  
}

Caso 2: Cuando se debe mostrar un mensaje de salida al usuario

{
    "status" : "execution",
    "message":"Please check your screen.",
    "card":[],
    "data":{},
    "broadcast":{},
    "trigger":{},
    "followup" : {}    
}

Hay algunas restricciones a considerar con las respuestas recibidas de las URLs de Webhook, tales como:

• El tamaño máximo de la respuesta es 100 KB.
• La duración máxima del tiempo de espera de la solicitud es 5 segundos.

Si la respuesta no cumple con las directrices anteriores, se enviará un mensaje de fallo como respuesta al usuario.

Proteger las Llamadas de Webhook

Las solicitudes de Webhook pueden protegerse para que el servidor de Webhook pueda validar si la solicitud proviene de ConvoKraft, evitando así el procesamiento de solicitudes no confiables. ConvoKraft usa el criptosistema Digital Signature Algorithm (DSA) para generar claves de seguridad, que deben ser utilizadas por el servidor de Webhook para validar la solicitud.

1. Una vez que optas por proteger tus llamadas de webhook al elegir la plataforma de desarrollo, ConvoKraft genera automáticamente una clave privada y una clave pública basadas en el criptosistema DSA. Ambas claves se cifran y se almacenarán en los servidores de ConvoKraft, y solo la clave pública se expondrá al desarrollador en la consola de Catalyst.

2. Al enviar una solicitud al servidor de Webhook, ConvoKraft genera una firma digital usando la clave privada almacenada y envía la firma en el encabezado de la solicitud X-CONVOKRAFT-SIGNATURE. Cuando el usuario escribe un mensaje en la ventana de chat, el mensaje se cifra con la clave privada y se envía en el cuerpo de la solicitud al servidor de webhook junto con la firma digital en el encabezado.

3. Cuando el servidor de Webhook recibe este mensaje, hace una comparación de la firma digital recibida en la solicitud y la firma original creada usando la clave pública cifrada. Si se encuentra una discrepancia, significa que el mensaje ha sido manipulado.

Implementación

Una vez que creas un bot, puedes elegir webhooks como la plataforma de desarrollo y seguir los pasos a continuación:

1. Ingresa la URL del webhook de tu servidor externo en el que reside el código de la lógica de negocio. Al ejecutar las acciones configuradas del bot, se accederá a esta URL.

2. Puedes elegir invocar la URL del webhook ya sea al final de cada mensaje del usuario en la conversación o cada vez que termina un contexto particular de la conversación.

   

3. Una vez creado el bot, podrás ver la página de detalles del Bot que lista la información crucial de tu bot de ConvoKraft.

   Para ver la clave pública generada, haz clic en el botón Show key en la página de detalles del Bot.

   

   Al hacer clic en la opción Show key, la ventana emergente Security Key mostrará la clave pública.

   

   Esta clave pública se utilizará en el entorno de desarrollo inmediatamente. Se utilizará en el entorno de producción una vez que despliegues tu proyecto de Catalyst.