Automate Your Workflows - EnageLab OTP Callback Settings Guide

Visión general

Configurar direcciones de callback para recibir callbacks de datos del servicio EngageLab OTP para "Message Status" y "Notification Messages", y utilizar los datos de callback para análisis estadístico, reenvío basado en estrategias o activación de alertas del sistema.

• Message Status: Después de que un usuario envíe un mensaje OTP, este estado incluye planificado, enviado, entregado, leído, verificado, etc.
• Notification Messages: Principalmente eventos del sistema, como baja tasa de verificación, saldo insuficiente, etc.

Configurar callback

En la página "Configuration Management" -> "Callback Settings", hacer clic en "Configure Callback" para configurar el callback del servicio EngageLab OTP.

Como se muestra en la imagen anterior, completar secuencialmente "Callback Description", "Callback Address", "Username", "Authorization", "Callback Events", etc.

• Marcar los eventos de callback para enviar información a la dirección especificada cuando se produzcan los eventos seleccionados.
• Hacer clic en el lado derecho del estado del mensaje y la respuesta del mensaje para ver los ejemplos correspondientes.

Configurar la dirección de callback

Al configurar la dirección de callback, el sistema EngageLab OTP enviará una solicitud HTTP POST a la dirección. El servicio de desarrollador correspondiente debe responder con un código de estado HTTP 200 en un plazo de 3 segundos; de lo contrario, el sistema considerará la dirección como no válida.

• El servicio de desarrollador solo debe responder con un código de estado HTTP 200, sin devolver ningún mensaje de respuesta.

Ejemplo de solicitud

Suponga que la dirección de callback configurada es https://example.engagelabotp.callback.com. Se enviará el siguiente mensaje vacío a la dirección, representado con un comando curl:

              
              curl -X POST https://example.engagelabotp.callback.com -d ''

            

Ejemplo de respuesta

El servicio de desarrollador en la dirección de callback solo debe responder con un código de estado HTTP 200 después de recibir la solicitud POST, como se muestra a continuación:

              
              HTTP/1.1 200 OK
Content-Length: 0

            

Configuración del mecanismo de seguridad de la dirección de callback

• Configuración de nombre de usuario

Esta es una operación opcional. Si se establece un nombre de usuario, también se debe completar un secreto.

Para garantizar que el origen del mensaje sea EngageLab, se puede optar por autenticar el origen de los datos POST.

Tras configurar el nombre de usuario y el secreto, los datos enviados por EngageLab incluirán el encabezado HTTP: X-CALLBACK-ID. El valor de X-CALLBACK-ID será timestamp={timestamp};nonce={nonce};username={username};signature={signature}

Por ejemplo:

              
              X-CALLBACK-ID: timestamp=1681991058;nonce=123123123123;username=test;signature=59682d71e2aa2747252e4e62c15f6f241ddecc8ff08999eda7e0c4451207a16b

            

El timestamp es la marca de tiempo del mensaje de callback (estándar), nonce es un número aleatorio y signature es la información de firma. El método de firma es: signature=HMAC-SHA256(secret, timestamp+nonce+username),

A continuación se muestra un ejemplo de código en Python para calcular signature:

              
              import hashlib, hmac
def verify(username, secret, timestamp, nonce, signature):
    return signature == hmac.new(
        key=secret,
        msg='{}{}{}'.format(timestamp, nonce, username),
        digestmod=hashlib.sha256).hexdigest()

            

• Configuración de autorización

Esta es una operación opcional. Si su dirección de callback requiere autenticación para las solicitudes procedentes de EngageLab, proporcione aquí la información de autenticación. EngageLab incluirá este Authorization en la solicitud.

Cuerpo de la solicitud de callback

Cuando se activa un evento de callback, el servicio del sistema EngageLab OTP enviará datos a la dirección de callback.

Ejemplo de solicitud de "Message Status"

Message status incluye:

• plan: Planificado para el envío
• sent: Enviado
• sent_failed: Error en el envío
• delivered: Entregado
• delivered_failed: Error en la entrega
• verified: Verificado
• verified_failed: Error en la verificación
• verified_timeout: Tiempo de espera de verificación agotado

              
              {
    "total": 2,					// Total count
    "rows": [{                  // Data
        "message_id": "1742442805608914944",    // Message ID
        "to": "+8615989574757",            // Receiver
        "server": "otp",                    // Service, fixed as otp
        "channel": "otp",                   // Channel, fixed as otp
        "itime": 1704265712,                // Creation time of this data
        "status": {                         // Message status
            "message_status": "plan",       // Message status, 'plan' for planned sending, 'sent' for sent, 'sent_failed' for sending failed
            "status_data": {                // Status data
                "msg_time": 170426571,     // Message send time
                "message_id": "1742442805608914944",    // Message ID
                "template_key": "auto_create_templateu25az170295320745",    // Template key
                "business_id": "100917676394736"        // business ID
            },
            "error_code": 0
        }
    }, {
        "message_id": "1742442805608914944",
        "to": "+8615989574757",
        "server": "otp",
        "channel": "otp",
        "itime": 1704265712,
        "status": {
            "message_status": "sent_failed",
            "status_data": {
                "msg_time": 1704265712,
                "message_id": "1742442805608914944",
                "template_key": "auto_create_templateu25az170295320745",
                "business_id": "100917676394736"
            },
            "error_code":5001,      // Error code
            "error_detail":{    // Error details
                "message":"sender config is invalid"        // Error message
            }
        }
    }]
}

            

Ejemplo de solicitud de "Notification Messages"

Eventos:

• insufficient_balance: Saldo por debajo del umbral de alerta

              
              {
    "total": 1,
    "rows": [{
        "server": "otp",
        "itime": 1712458844,
        "notification": {
            "event": "insufficient_balance",
            "notification_data": {
                "business_id": "1744569418236633088",
                "remain_balance": -0.005,                    // Current balance;
                "balance_threshold": 2                       // Alert threshold;
            }
        }
    }]
}