Logo Site EngageLab Mark Colored TransparentDocumentación
OTP
Server Center
DocumentaciónReferencia de la API
Buscar
Iniciar sesión
Referencia de la API/Configuración de callbacks
Referencia de la APIConfiguración de callbacks...

Descripción de la configuración de callbacks

Última actualización：hace 7 días

Esta sección describe cómo configurar la dirección de callback de EngageLab OTP, así como los mecanismos de verificación de seguridad relacionados, para garantizar la fiabilidad y la seguridad de los datos del callback.

Configuración y verificación de la dirección de callback

Tras configurar la dirección de callback, EngageLab OTP enviará automáticamente una solicitud HTTP POST a dicha dirección para comprobar la disponibilidad del endpoint. Su servicio debe devolver un código de estado HTTP 200 en un plazo de 3 segundos; de lo contrario, el sistema considerará que la dirección no está disponible.

Nota:
Para garantizar la recepción correcta de los datos del callback, agregue 119.8.170.74 y 114.119.180.30 a la lista blanca del firewall de su servidor.

Ejemplo de solicitud

Suponiendo que su dirección de callback es https://example.engagelabotp.callback.com, el sistema enviará la siguiente solicitud:

curl -X POST https://example.engagelabotp.callback.com -d '{}'
              
              curl -X POST https://example.engagelabotp.callback.com -d '{}'
Este bloque de código se muestra en una ventana flotante

Requisitos de la respuesta

Su servicio solo necesita devolver un código de estado HTTP 200, sin necesidad de devolver ningún contenido. Por ejemplo:

HTTP/1.1 200 OK Content-Length: 0
              
              HTTP/1.1 200 OK
Content-Length: 0
Este bloque de código se muestra en una ventana flotante

Nota:
La verificación de la dirección de callback solo evalúa el código de estado HTTP y no exige que se devuelva un contenido concreto. Asegúrese de que el endpoint de su servicio pueda responder correctamente con un 200 en un plazo de 3 segundos.

Mecanismos de seguridad de los callbacks

Para garantizar la seguridad de los datos del callback y la fiabilidad de su origen, EngageLab OTP admite varios métodos de verificación de seguridad.

Verificación con nombre de usuario y clave secreta (opcional)

  • Configuración opcional. Si se establece un nombre de usuario, también debe establecerse una clave secreta.
  • Una vez configurado, EngageLab añade el campo X-CALLBACK-ID en el encabezado HTTP de cada solicitud de callback, con el siguiente formato:
X-CALLBACK-ID: timestamp={timestamp};nonce={nonce};username={username};signature={signature}
              
              X-CALLBACK-ID: timestamp={timestamp};nonce={nonce};username={username};signature={signature}
Este bloque de código se muestra en una ventana flotante
  • Donde:
    • timestamp: marca de tiempo del envío del callback
    • nonce: número aleatorio
    • username: el nombre de usuario que configuró
    • signature: información de la firma, calculada de la siguiente manera

Método de cálculo de la firma (ejemplo en Python)

import hashlib, hmac def verify(username, secret, timestamp, nonce, signature): return signature == hmac.new( key=secret.encode(), msg=f'{timestamp}{nonce}{username}'.encode(), digestmod=hashlib.sha256 ).hexdigest()
              
              import hashlib, hmac
def verify(username, secret, timestamp, nonce, signature):
    return signature == hmac.new(
        key=secret.encode(),
        msg=f'{timestamp}{nonce}{username}'.encode(),
        digestmod=hashlib.sha256
    ).hexdigest()
Este bloque de código se muestra en una ventana flotante
  • El servidor puede verificar la legitimidad de la solicitud de callback mediante el método anterior.

Autenticación con Authorization (opcional)

  • Si el endpoint de su callback requiere autenticación (como Basic Auth, Bearer Token, etc.), puede indicar la información de Authorization durante la configuración.
  • EngageLab incluirá automáticamente ese campo Authorization en la solicitud, lo que facilita que su servicio verifique la identidad de la solicitud.

Descripción de los eventos de callback

Estado del mensaje

El estado del mensaje se utiliza para seguir los cambios de estado de cada mensaje a lo largo de su ciclo de vida. Permite conocer en tiempo real el progreso en cada etapa: envío, entrega, verificación, etc., lo que facilita el análisis estadístico, el tratamiento de excepciones y la optimización de la experiencia del usuario.

Identificador del evento Descripción
plan El mensaje está programado para enviarse y entra en la cola de envío
target_valid El número de destino es válido
target_invalid El número de destino no es válido
sent El mensaje se envió correctamente
sent_failed Error al enviar el mensaje
delivered El mensaje se entregó en el dispositivo del usuario
delivered_failed El mensaje se envió, pero no se pudo entregar en el dispositivo del usuario
verified El usuario completó correctamente la verificación OTP
verified_failed La verificación del usuario falló
verified_timeout El usuario no completó la verificación en el tiempo establecido y se agotó el tiempo de espera

Estructura de datos del callback

Estructura externa

{ "total": 1, "rows": [ { // objeto ReportLifecycle } ] }
              
              {
  "total": 1,
  "rows": [
    {
      // objeto ReportLifecycle
    }
  ]
}
Este bloque de código se muestra en una ventana flotante
Nombre del campo Tipo Descripción
total int Número de registros incluidos en este callback
rows array Array de datos de estado del ciclo de vida

Objeto ReportLifecycle

Nombre del campo Tipo Descripción
message_id string ID único del mensaje
to string Número del destinatario
server string Tipo de servicio (por ejemplo, otp)
channel string Tipo de canal
itime int64 Marca de tiempo del callback (segundos)
custom_args object Parámetros personalizados (se devuelven si se pasaron al enviar)
status object Objeto con los detalles del estado

Objeto status

Nombre del campo Tipo Descripción
message_status string Estado actual del mensaje (véase la tabla siguiente)
status_data object Objeto de datos de estado
billing object Objeto con información de facturación (se devuelve cuando hay facturación)
error_code int Código de error; 0 indica que no hay error
error_detail object Detalles del error (se devuelve cuando se produce un error)

Objeto status_data

Nombre del campo Tipo Descripción
msg_time int64 Marca de tiempo de creación del mensaje (segundos)
message_id string ID del mensaje
current_send_channel string Nombre del canal de envío actual
template_key string Key de configuración de la plantilla
business_id string ID de negocio

Objeto billing (se devuelve cuando hay facturación)

Nombre del campo Tipo Descripción
cost float64 Importe del coste
currency string Moneda, fija en "USD"

Por lo general, solo los mensajes en la etapa sent incluyen información de facturación.

Objeto error_detail (se devuelve cuando se produce un error)

Nombre del campo Tipo Descripción
message string Descripción del mensaje de error

Ejemplo: mensaje enviado correctamente

{ "total": 1, "rows": [ { "message_id": "123456789", "to": "+6598765432", "server": "sms", "channel": "sms", "itime": 1701234567, "custom_args": { "order_id": "ORDER123", "user_id": "USER456" }, "status": { "message_status": "sent", "status_data": { "msg_time": 1701234560, "message_id": "123456789", "current_send_channel": "CHANNEL_A", "template_key": "verify_code", "business_id": "1001" }, "billing": { "cost": 0.005, "currency": "USD" }, "error_code": 0 } } ] }
              
              {
  "total": 1,
  "rows": [
    {
      "message_id": "123456789",
      "to": "+6598765432",
      "server": "sms",
      "channel": "sms",
      "itime": 1701234567,
      "custom_args": {
        "order_id": "ORDER123",
        "user_id": "USER456"
      },
      "status": {
        "message_status": "sent",
        "status_data": {
          "msg_time": 1701234560,
          "message_id": "123456789",
          "current_send_channel": "CHANNEL_A",
          "template_key": "verify_code",
          "business_id": "1001"
        },
        "billing": {
          "cost": 0.005,
          "currency": "USD"
        },
        "error_code": 0
      }
    }
  ]
}
Este bloque de código se muestra en una ventana flotante

Ejemplo: error al enviar el mensaje

{ "total": 1, "rows": [ { "message_id": "123456790", "to": "+6598765433", "server": "sms", "channel": "sms", "itime": 1701234568, "status": { "message_status": "sent_fail", "status_data": { "msg_time": 1701234561, "message_id": "123456790", "current_send_channel": "CHANNEL_B", "template_key": "verify_code", "business_id": "1001" }, "error_code": 4001, "error_detail": { "message": "Invalid phone number" } } } ] }
              
              {
  "total": 1,
  "rows": [
    {
      "message_id": "123456790",
      "to": "+6598765433",
      "server": "sms",
      "channel": "sms",
      "itime": 1701234568,
      "status": {
        "message_status": "sent_fail",
        "status_data": {
          "msg_time": 1701234561,
          "message_id": "123456790",
          "current_send_channel": "CHANNEL_B",
          "template_key": "verify_code",
          "business_id": "1001"
        },
        "error_code": 4001,
        "error_detail": {
          "message": "Invalid phone number"
        }
      }
    }
  ]
}
Este bloque de código se muestra en una ventana flotante

Notificaciones del sistema

Las notificaciones del sistema hacen referencia a eventos de negocio o alertas a nivel de sistema. Sirven para avisar a la parte de negocio sobre información importante como el estado de funcionamiento del servicio, el saldo o la revisión de plantillas, lo que facilita su tratamiento oportuno y la advertencia temprana de riesgos.

Identificador del evento Descripción
insufficient_verification_rate La tasa de verificación está por debajo del umbral establecido
insufficient_balance Saldo de la cuenta insuficiente
template_audit_result Notificación del resultado de la revisión de una plantilla

Ejemplo

{ "total": 1, "rows": [{ "server": "otp", "itime": 1712458844, "notification": { "event": "insufficient_balance", "notification_data": { "business_id": "1744569418236633088", "remain_balance": -0.005, // saldo actual; "balance_threshold": 2 // umbral de alerta; } } }] }
              
              {
    "total": 1,
    "rows": [{
        "server": "otp",
        "itime": 1712458844,
        "notification": {
            "event": "insufficient_balance",
            "notification_data": {
                "business_id": "1744569418236633088",
                "remain_balance": -0.005,                    // saldo actual;
                "balance_threshold": 2                       // umbral de alerta;
            }
        }
    }]
}
Este bloque de código se muestra en una ventana flotante

Respuestas de mensaje

Las respuestas de mensaje se refieren principalmente a los eventos de respuesta de callback que se producen al interactuar con usuarios o sistemas externos.

Identificador del evento Descripción
uplink_message Contenido del mensaje entrante (uplink) que el usuario responde, por ejemplo, mediante SMS

Ejemplo

{ "total": 1, "rows": [ { "server": "otp", "itime": 1741083306, "message_id": "0", "business_id": "0", "response": { "event": "uplink_message", "response_data": { "message_sid": "SM1234567890", "account_sid": "AC1234567890", "from": "+1234567890", "to": "+0987654321", "body": "Hello, it's time to struggle!" } } } ] }
              
              {
    "total": 1,
    "rows": [
        {
            "server": "otp",
            "itime": 1741083306,
            "message_id": "0",
            "business_id": "0",
            "response": {
                "event": "uplink_message",
                "response_data": {
                    "message_sid": "SM1234567890",
                    "account_sid": "AC1234567890",
                    "from": "+1234567890",
                    "to": "+0987654321",
                    "body": "Hello, it's time to struggle!"
                }
            }
        }
    ]
}
Este bloque de código se muestra en una ventana flotante

Eventos del sistema

Los eventos del sistema abarcan las acciones relacionadas con la cuenta, las plantillas, las llamadas a la API, etc. Facilitan la supervisión, la auditoría y el tratamiento automatizado de operaciones clave como el inicio de sesión de la cuenta, los cambios de claves y las llamadas a la API.

Identificador del evento Descripción
account_login Notificación de operaciones relacionadas con el inicio de sesión de la cuenta
key_manage Notificación de operaciones relacionadas con el cambio y la gestión de claves
msg_history Notificación de operaciones relacionadas con la consulta del historial de mensajes
template_manage Notificación de operaciones como la creación, modificación y eliminación de plantillas
api_call Notificación de operaciones relacionadas con las llamadas a la API

Estructura de datos del callback

Estructura externa

{ "total": 1, "rows": [ { // objeto de evento del sistema } ] }
              
              {
  "total": 1,
  "rows": [
    {
      // objeto de evento del sistema
    }
  ]
}
Este bloque de código se muestra en una ventana flotante
Campo Tipo Descripción
total int64 Número total de eventos incluidos en este callback
rows array Array de objetos de eventos del sistema

Objeto de evento del sistema

Campo Tipo Descripción
server string Fijo en "otp"
itime int64 Marca de tiempo en que se produjo el evento (segundos)
system_event object Contenido del evento del sistema

Objeto system_event

Campo Tipo Descripción
event string Tipo de evento
data object Datos del evento

Objeto data

Campo Tipo Descripción
business_id string ID de negocio
org_id string ID de la organización
operator object Información del operador

Objeto operator

Campo Tipo Descripción
email string Correo del operador (si lo hay)
api_key string API Key (si la hay)
ip_address string IP de la operación

Estructura de la solicitud

{ "total": 1, "rows": [ { "server": "otp", "itime": 1694012345, "system_event": { "event": "account_login", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "api_key": "api-xxxx", "ip_address": "1.2.3.4" }, "account_login": { "action": "login_success" } } } } ] }
              
              {
  "total": 1,
  "rows": [
    {
      "server": "otp",
      "itime": 1694012345,
      "system_event": {
        "event": "account_login",
        "data": {
          "business_id": "123",
          "org_id": "org-abc",
          "operator": {
            "email": "foo@example.com",
            "api_key": "api-xxxx",
            "ip_address": "1.2.3.4"
          },
          "account_login": {
            "action": "login_success"
          }
        }
      }
    }
  ]
}
Este bloque de código se muestra en una ventana flotante

Evento de inicio de sesión de la cuenta

Campo Tipo Descripción
action string Inicio de sesión correcto / Inicio de sesión fallido / Cierre de sesión
fail_reason string Motivo del inicio de sesión fallido; solo se devuelve cuando es login_failed

Ejemplo

{ "event": "account_login", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "ip_address": "1.2.3.4" }, "account_login": { "action": "login_success" } } }
              
              {
  "event": "account_login",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "email": "foo@example.com",
      "ip_address": "1.2.3.4"
    },
    "account_login": {
      "action": "login_success"
    }
  }
}
Este bloque de código se muestra en una ventana flotante

Evento de gestión de plantillas

Campo Tipo Descripción
action string Crear plantilla / Actualizar plantilla / Eliminar plantilla
template_id string ID de la plantilla
template_name string Nombre de la plantilla

Ejemplo

{ "event": "template_manage", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "ip_address": "1.2.3.4" }, "template_manage": { "action": "update template", "template_id": "tmpl-456", "template_name": "Verification Code" } } }
              
              {
  "event": "template_manage",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "email": "foo@example.com",
      "ip_address": "1.2.3.4"
    },
    "template_manage": {
      "action": "update template",
      "template_id": "tmpl-456",
      "template_name": "Verification Code"
    }
  }
}
Este bloque de código se muestra en una ventana flotante

Evento de gestión de claves

Campo Tipo Descripción
action string Valores de enumeración:
create api_key: crear API Key
update api_key: actualizar API Key
delete api_key: eliminar API Key
view api_secret: ver API Secret
api_key string API Key
description string Descripción (opcional)

Ejemplo

{ "event": "key_manage", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "ip_address": "1.2.3.4" }, "key_manage": { "action": "create", "api_key": "apikey-789", "description": "Clave nueva" } } }
              
              {
  "event": "key_manage",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "email": "foo@example.com",
      "ip_address": "1.2.3.4"
    },
    "key_manage": {
      "action": "create",
      "api_key": "apikey-789",
      "description": "Clave nueva"
    }
  }
}
Este bloque de código se muestra en una ventana flotante

Evento de llamada a la API

Campo Tipo Descripción
api_path string Ruta del endpoint
method string Método HTTP

Ejemplo

{ "event": "api_call", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "api_key": "apikey-789", "ip_address": "1.2.3.4" }, "api_call": { "api_path": "/api/v1/messages/send", "method": "POST" } } }
              
              {
  "event": "api_call",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "api_key": "apikey-789",
      "ip_address": "1.2.3.4"
    },
    "api_call": {
      "api_path": "/api/v1/messages/send",
      "method": "POST"
    }
  }
}
Este bloque de código se muestra en una ventana flotante
Icon Solid Transparent White Qiyu
Contacto