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.
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
PUBLICARsolicitud.
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_idque 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 | Enviado el |
|---|---|
| Un dispositivo envía un SMS desde la tarjeta SIM a Simbase (MO, originado en el móvil) |
| Se envía un SMS a la tarjeta SIM, desde el panel de control o mediante la API (MT, terminación móvil) |
| Se ha detectado una tarjeta SIM en un dispositivo con un IMEI diferente |
| La tarjeta SIM está activada |
| Una tarjeta SIM está desactivada |
| Una tarjeta SIM supera un umbral establecido en sus límites de uso |
| Se crea un nuevo registro de uso (CDR) para una tarjeta SIM |
simcard.sms.mosimcard.sms.mtsimcard.security.imei_changedsimcard.state.enabledsimcard.state.disabledsimcard.usage.threshold_exceededsimcard.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.
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:
Para qué sirve cada campo del sobre:
tipo_de_eventote indica de qué evento se trata y, por lo tanto, qué campos debes esperar enevento.event_idEs exclusivo de este evento y es el mismo en cada nuevo intento. Úsalo para ignorar los duplicados.marca de tiempoes la fecha en la que Simbase registró el evento, en UTC (RFC 3339).correlation_idrelaciona 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_clientees 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
Se ha superado el límite de uso (uso en bytes, el umbral es null (si no está configurado)
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
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.
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.
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.
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.Responde rápido. Tu punto final debería devolver un
2xxestablecer el estado en cuanto llegue la solicitud y realizar el trabajo propiamente dicho después.Comprueba la firma antes de reaccionar ante un suceso. Véase Seguridad.
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 webhookyfirma del webhook, que se utiliza para verificar la solicitudX-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_idpara ignorar las repeticiones.No siempre en orden. Los eventos pueden aparecer en un orden distinto al que tuvieron lugar. Ordenar por
marca de tiempocuando el orden es importante, por ejemplo, en los cambios de estado.¿Qué se considera un éxito?: cualquiera
2xxcódigo de estado.Se ha vuelto a intentar con un intervalo de espera de hasta 4 horas: tiempos de espera,
408,429y5xxrespuestas. ARetry-AfterSe respeta el encabezado.No se ha vuelto a intentar: cualquier otro código de estado, incluidas las redirecciones.
Suspendidos de inmediato: a
410 DesaparecidoLa 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.
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 | Tipo de evento |
|---|---|
SMS recibido ( |
|
Cambio del IMEI ( |
|
Cambio de estado de la tarjeta SIM ( |
|
Se han alcanzado los límites de uso ( |
|
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
eventocampo, 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_estadoynuevo_estadocampos.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:
Añade un destino para los mismos tipos de eventos, que apunte a una nueva ruta en tu punto final.
Actualiza tu código para leer la nueva carga útil y verificar la firma.
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.
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



