Eventos: notificaciones en tiempo real de tus SIM

Los eventos avisan a tus sistemas en el momento en que ocurre algo en tus tarjetas SIM de Simbase. Cuando un dispositivo envía un SMS, se cambia una tarjeta SIM a otro dispositivo, se desactiva una tarjeta SIM o se supera un límite de uso, Simbase envía los detalles a la URL que elijas en cuestión de segundos, por lo que nunca tendrás que consultar la API para averiguarlo.

Los eventos sustituyen a los webhooks antiguos. Abarcan las mismas situaciones y añaden algunas características que los clientes venían solicitando: más tipos de eventos, un único destino para muchos tipos de eventos, solicitudes firmadas que se pueden verificar, un registro de entregas y un mayor número de reintentos.

¿Listo para la puesta en marcha? Añadir un destino en la página «Integraciones» del panel de control.

¿Ya utilizas los webhooks?No hay ningún problema. Los webhooks heredados seguirán funcionando en un futuro próximo, pero no recibirán nuevas funciones. Asegúrate de utilizar «Events» para cualquier cosa nueva.

Cómo funcionan los eventos

Hay dos ideas que lo abarcan todo:

  • Un evento Es un registro de un hecho concreto, como «SIM 8900…567 envió un SMS». Cada evento tiene un tipo, un identificador único, una marca de tiempo y los detalles propios de su tipo.

  • Un destino es donde se envían los eventos. Hoy en día se trata de un webhook: una URL HTTPS que recibe cada evento en formato JSON PUBLICAR solicitud.

Cuando se produce un evento, Simbase lo envía a todos los destinos cuyo filtro coincida con su tipo. Tu punto final responde con un 2xx código de estado.

La URL puede ser cualquier dirección que admita una solicitud POST a través de HTTPS:

  • Una plataforma de automatización sin código, como Zapier o Make.com

  • Una herramienta de chat para equipos como Slack o Microsoft Teams (normalmente con Zapier o Make.com como intermediarios para modificar el mensaje)

  • Una ruta en tu propio servidor, en cualquier lenguaje

  • Una función sin servidor en AWS Lambda, Vercel, Cloudflare Workers, Google Cloud Functions y otras plataformas similares

¿Qué novedades hay en comparación con los webhooks?

  • Más tipos de eventos. Ahora están disponibles los SMS enviados a una tarjeta SIM y todos los nuevos registros de uso (CDR), además de los cuatro eventos anteriores.

  • Un destino, muchos eventos. Un webhook heredado transportaba un solo tipo de evento. El filtro de un destino puede incluir tantos tipos de eventos como se desee, o incluso todos ellos.

  • Solicitudes firmadas. Cada solicitud lleva una firma, por lo que tu punto final puede confirmar que realmente procede de Simbase y que no se ha modificado durante el trayecto.

  • A prueba de duplicados. Cada evento tiene un event_id que no cambia en ningún intento de entrega.

  • Reintentos más prolongados. Las entregas fallidas se vuelven a intentar con un intervalo de espera de hasta 4 horas, en lugar de tres intentos.

  • Registro de entregas. Puedes consultar los intentos de entrega de los últimos 15 días para cada destino, incluidos los fallidos.

  • El sondeo como alternativa. Los eventos se conservan durante 30 días y también se pueden consultar a través de la API, sin necesidad de especificar un destino.

Tipos de eventos

Los nombres de los tipos de eventos se componen de partes separadas por puntos, de lo general a lo específico, como simcard.sms.mo. Un filtro puede coincidir con un tipo de evento completo o solo con el inicio del nombre, por lo que un único filtro puede abarcar varios tipos de eventos relacionados a la vez.

Los eventos por SMS utilizan la terminología estándar de la telefonía móvil. MO (originado en el móvil) es un SMS enviado por la tarjeta SIM, desde el dispositivo a Simbase. MT (terminado en móvil) es un SMS enviado a la tarjeta SIM, desde el panel de control o la API, al dispositivo.

Tipo de evento
  • simcard.sms.mo
  • simcard.sms.mt
  • simcard.security.imei_changed
  • simcard.state.enabled
  • simcard.state.disabled
  • simcard.usage.threshold_exceeded
  • simcard.usage.cdr

Filtrado de eventos

Cuando creas un destino, su filtro determina qué recibe:

  • Un único tipo de evento, como simcard.state.desactivado, para «avísame cuando una tarjeta SIM se desconecte».

  • Un prefijo, como simcard.sms, para cada tipo de evento que comience por ello. En este caso, se trata tanto de los SMS de MO como de los de MT.

  • Todo: deja el filtro en blanco para recibir todos los tipos de eventos.

No te pases con los CDR«simcard.usage.cdr» es, con diferencia, el tipo de evento más frecuente: una tarjeta SIM activa puede generar muchos registros al día. Un filtro de «simcard» o «simcard.usage» lo incluye. Incluye los CDR solo si realmente almacenas o procesas registros de uso, y asegúrate de que tu punto final pueda gestionar ese volumen.

Lo que la gente crea con Events

  • SMS desde dispositivos (MO): reenviar los mensajes del dispositivo a Slack o Teams, registrarlos en una hoja de cálculo de Google a través de Zapier, procesar las lecturas de los sensores en tu base de datos o reenviarlas a un número de teléfono a través de Twilio. Ver SMS.

  • SMS a dispositivos (MT): Confirmar que se ha enviado un SMS de comando o de configuración a un dispositivo y llevar un registro de lo que se ha enviado.

  • Se ha cambiado el IMEI: enviar alertas o crear un ticket cuando una tarjeta SIM aparezca en un dispositivo inesperado, o desactivarla a través de la API. El evento incluye el estado de protección contra robo de la tarjeta SIM, para que sepas si el cambio se ha bloqueado.

  • Tarjeta SIM activada o desactivada: mantén sincronizada tu base de datos de CRM o de activos, avisa al servicio de asistencia antes de que llame el cliente o inicia la facturación cuando se active una tarjeta SIM. Ver Estado de la tarjeta SIM.

  • Se ha superado el límite de uso: detectar a tiempo un dispositivo fuera de control, abrir una incidencia en PagerDuty o avisar al propietario del dispositivo. Véase Límites de uso.

  • CDR: Integra el uso de streaming en tu propio sistema de facturación o análisis, en lugar de exportarlo.

Cómo es un evento

Todas las solicitudes tienen la misma estructura externa, la sobre, con los detalles del evento en el interior del evento campo. A continuación se muestra un SMS enviado por un dispositivo:

{
"event_type": "simcard.sms.mo",
"event_id": "01KPX0BH46PVJ89YE6446Q086M",
"timestamp": "2026-11-13T09:30:12.418000Z",
"correlation_id": "123e4567-e89b-12d3-a456-426614174001",
"customer_id": "C123123123123",
"event": {
"iccid": "8900000000001234567",
"message": "temp=21.4;door=closed",
"timestamp": "2026-11-13T09:30:11Z"
}
}

Para qué sirve cada campo del sobre:

  • tipo_de_evento te indica de qué evento se trata y, por lo tanto, qué campos debes esperar en evento.

  • event_id Es exclusivo de este evento y es el mismo en cada nuevo intento. Úsalo para ignorar los duplicados.

  • marca de tiempo es la fecha en la que Simbase registró el evento, en UTC (RFC 3339).

  • correlation_id relaciona el evento con la causa que lo provocó. Inclúyelo cuando te pongas en contacto con el servicio de asistencia para informar de un evento.

  • id_cliente es tu cuenta de Simbase.

Solo el evento Los cambios en las partes varían según el tipo. Dos ejemplos más:

Se ha cambiado el IMEI

{
"event": {
"iccid": "8900000000001234567",
"imei_old": "356938035643021",
"imei_new": "356938035643039",
"imei_lock": "off"
}
}

Se ha superado el límite de uso (uso en bytes, el umbral es null (si no está configurado)

{
"event": {
"iccid": "8900000000001234567",
"usage_data": 105906176,
"usage_sms": 3,
"threshold_data": 104857600,
"threshold_sms": null
}
}

Los demás tipos siguen el mismo patrón. Los eventos de estado de la SIM contienen el iccid. Los CDR contienen la hora de inicio y de finalización, el tipo, el volumen y la red (MCC y MNC). La lista completa de campos para cada tipo se encuentra en el Referencia de la API.

Configurar un destino

  1. Decide qué necesitas. Qué tipos de eventos y qué campos de cada uno de ellos vas a utilizar. Empieza poco a poco; ya podrás modificar el filtro más adelante.

  2. Consigue una URL HTTPS que acepte solicitudes POST: una ruta en tu backend, una función sin servidor o una URL de webhook de Zapier o Make.com. Debe ser accesible desde la red pública de Internet.

  3. Añade el destino. En el cuadro de mando, abrir Integraciones y añade un nuevo destino. Introduce la URL, asígnale un nombre que te resulte reconocible y configura el Filtro a los tipos de evento que desees.

  4. Guarda el secreto de firma. El panel de control muestra un secreto que empieza por whsec_. Solo se muestra una vez, así que guárdala en un lugar seguro, como tu gestor de contraseñas o el almacén de secretos de tu aplicación.

  5. Responde rápido. Tu punto final debería devolver un 2xx establecer el estado en cuanto llegue la solicitud y realizar el trabajo propiamente dicho después.

  6. Comprueba la firma antes de reaccionar ante un suceso. Véase Seguridad.

  7. Consulta el registro de entregas En los primeros eventos, para confirmar que llegan y que tu punto final responde con 2xx.

También puedes crear y gestionar destinos a través de la API, utilizando una clave de API con los ámbitos de integración.

Especificaciones

Método y encabezados

Todas las entregas se realizan mediante HTTPS PUBLICAR con un cuerpo JSON, enviada únicamente a direcciones IP públicas. Cada solicitud incluye estos encabezados:

  • webhook-id, marca de tiempo del webhook y firma del webhook, que se utiliza para verificar la solicitud

  • X-Simbase-Integración-Id, el destino al que se envió la solicitud

Seguridad

Las solicitudes se firman tras la apertura Webhooks estándar especificación. Simbase firma cada solicitud con el whsec_ secreto y guarda el resultado en el firma del webhook Encabezado. Al comprobarlo, se confirma que la solicitud procedía de Simbase y que no había sido alterada.

La forma más fácil es una de las opciones gratuitas Bibliotecas estándar de webhooks, disponible para la mayoría de los idiomas: solo tienes que pasar el cuerpo de la solicitud sin procesar, los encabezados y tu clave secreta, y la biblioteca se encarga del resto, incluido el rechazo de las solicitudes antiguas. El Referencia de la API También incluye un breve ejemplo para comprobarlo sin necesidad de utilizar ninguna biblioteca.

Hay dos cosas que hay que tener en cuenta:

  • Comprueba el cuerpo sin procesar. Comprueba que la firma coincide con el cuerpo tal y como se ha recibido, antes de que tu marco de trabajo analice o reformatee el JSON.

  • No confíes en las listas de direcciones IP permitidas. Los servidores de Simbase están distribuidos por todo el mundo y las direcciones desde las que envían datos cambian con el tiempo. La firma es la forma más fiable de verificarlo.

Si envías eventos a una herramienta sin código que no puede comprobar las firmas, considera la propia URL como un dato confidencial y no la compartas.

Si tu servidor utiliza un certificado TLS autofirmado, puedes desactivar la verificación del certificado para ese destino.

Entrega y reintentos

  • Al menos una vez. Un evento puede producirse más de una vez. Utiliza event_id para ignorar las repeticiones.

  • No siempre en orden. Los eventos pueden aparecer en un orden distinto al que tuvieron lugar. Ordenar por marca de tiempo cuando el orden es importante, por ejemplo, en los cambios de estado.

  • ¿Qué se considera un éxito?: cualquiera 2xx código de estado.

  • Se ha vuelto a intentar con un intervalo de espera de hasta 4 horas: tiempos de espera, 408, 429 y 5xx respuestas. A Retry-After Se respeta el encabezado.

  • No se ha vuelto a intentar: cualquier otro código de estado, incluidas las redirecciones.

  • Suspendidos de inmediato: a 410 Desaparecido La respuesta suspende el destino.

  • Suspendido tras 48 horas: Un destino que siga fallando durante 48 horas seguidas queda suspendido. Vuelve a activarlo desde el panel de control o la API para empezar a recibir nuevos eventos de nuevo.

RetenciónLos eventos se conservan durante 30 días. Los intentos de entrega se pueden consultar durante 15 días.

Migración desde los webhooks heredados

Los webhooks antiguos siguen funcionando, por lo que puedes ir a tu propio ritmo. Cada evento antiguo tiene un equivalente directo:

Webhook heredado
  • SMS recibido (SMS)

  • Cambio del IMEI (IMEI)

  • Cambio de estado de la tarjeta SIM (sim_state)

  • Se han alcanzado los límites de uso (límites_de_uso)

¿Qué cambios se producen en la carga útil?:

  • Los detalles se desplazan dentro de un evento campo, incluido en el sobre descrito anteriormente.

  • Las marcas de tiempo están en formato RFC 3339, en UTC, como 2026-11-13T09:30:12Z.

  • Un cambio de estado se compone ahora de dos tipos de eventos, uno para «activado» y otro para «desactivado», en lugar de antiguo_estado y nuevo_estado campos.

  • El consumo de datos se mide en bytes, en lugar de en MB.

  • No se incluye el nombre del dispositivo. Si lo necesitas, búscalo por el ICCID.

Una forma segura de cambiar:

  1. Añade un destino para los mismos tipos de eventos, que apunte a una nueva ruta en tu punto final.

  2. Actualiza tu código para leer la nueva carga útil y verificar la firma.

  3. Ejecuta ambos en paralelo durante unos días y compáralos. Es de esperar que cada cambio se produzca dos veces durante este tiempo, una vez por cada sistema.

  4. Elimina el webhook antiguo en Integraciones → Webhooks.

Preguntas frecuentes

No. Los webhooks antiguos seguirán funcionando en un futuro próximo, pero no incorporarán nuevas funciones. Las nuevas integraciones deben utilizar «Events».

La entrega se realiza al menos una vez, por lo que es posible que un nuevo intento llegue después de que tu punto final ya haya procesado el primer intento. Guarda el `event_id` de los eventos que hayas gestionado y omite los que ya hayas visto.

O bien devolvió `410 Desaparecido` o ha fallado durante 48 horas seguidas. Corrige el punto final, comprueba el registro de entrega para ver el error y, a continuación, vuelve a habilitar el destino en la página «Integraciones». Los eventos generados mientras estuvo suspendido no se reenvían, pero podrás consultarlos a través de la API durante 30 días.

Sí, consultándolos a través del API. Las consultas consumen tu cuota de API, por lo que un destino es la mejor opción para cualquier cosa en tiempo real.

Sí. Crea un destino para cada URL, cada uno con sus propios tipos de eventos.

No. El protocolo TLS es obligatorio para garantizar la privacidad de los datos y la seguridad de las comunicaciones. No obstante, puedes seguir utilizando un certificado autofirmado y desactivar la verificación del certificado TLS en el extremo de destino.

Relacionado

  • Webhooks (versión antigua): la forma anterior de recibir eventos, que sigue siendo compatible

  • Claves de API: crear una clave con los ámbitos necesarios para gestionar los destinos

  • SMS: los mensajes que hay detrás de los eventos de SMS y en qué se diferencian según el perfil

  • Protección contra robos: bloquear una tarjeta SIM a un IMEI concreto, lo cual se notifica en los eventos de cambio de IMEI

  • Estado de la tarjeta SIM: qué significan «Activado» y «Desactivado» y qué hace que cambien

  • Límites de uso: establecer los umbrales que dan lugar a eventos de umbral

  • API: gestionar destinos y consultar eventos mediante programación