Un webhook es un mensaje que recibe tu aplicación en el momento en que ocurre algo, en lugar de tener que preguntar «¿hay alguna novedad?» una y otra vez. Cuando se produce un evento en tu cuenta de Simbase, Simbase envía ese evento a una URL que tú controlas, en tiempo real.

Así es como se integra Simbase con el resto de tu entorno. Llega un SMS a una tarjeta SIM y se activa una notificación en tu canal de Slack. Un dispositivo cambia de IMEI y tu sistema de gestión de incidencias abre una incidencia. El consumo mensual de datos supera un umbral y se actualiza tu panel de control de uso. Todo ello sin necesidad de escribir código que consulte nuestra API.

Los webhooks abarcan los eventos que se producen en el entorno de Simbase: SMS entrantes, cambios en el IMEI, cambios en el estado de la tarjeta SIM, limitaciones de velocidad y umbrales de uso.

¿Estás listo para la puesta en marcha? Registra tu punto final de webhook en el panel de control para que Simbase sepa dónde enviar los eventos.

Cómo utiliza Simbase los webhooks

Cuando ocurre algo en tu cuenta, Simbase envía una solicitud POST HTTPS a la URL que especifiques, con un cuerpo JSON que describe el evento. Tu aplicación lee el cuerpo, realiza las acciones que desees con él y responde con un código de estado 2xx para confirmar que se ha recibido el mensaje.

No es necesario crear nada sofisticado en el lado receptor. La «URL que especifiques» puede ser cualquiera de las siguientes:

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

• Una herramienta de chat para equipos como Slack o Microsoft Teams, utilizando sus URL de webhooks entrantes integradas (ya sea directamente o mediante Zapier o Make.com como intermediarios)

• Una función en tu propio backend, en cualquier lenguaje

• Un proveedor externo de SMS, como Twilio o MessageBird, si quieres reenviar mensajes SMS a números de teléfono públicos

• Una función sin servidor en AWS Lambda, Vercel, Cloudflare Workers, Google Cloud Functions, etc.

Si nos facilitas una URL HTTPS, podremos transmitir eventos a través de ella.

Eventos de webhook

Simbase admite los siguientes tipos de eventos:

• Mensajes SMS recibidos

• Cambios en el IMEI

• Cambio de estado de la tarjeta SIM

• Limitación de velocidad

• El uso supera el umbral

Mensajes SMS recibidos

Las tarjetas SIM de Simbase funcionan dentro de lo que denominamos un «circuito SMS cerrado». En pocas palabras: tu tarjeta SIM puede enviar SMS a nuestro servidor al número corto +55555 y recibir SMS de nuestro servidor, pero no puede intercambiar SMS con ningún otro número de teléfono del mundo. Esto es a propósito. Se trata de una medida de seguridad que mantiene tu flota inaccesible desde la red pública de SMS, de modo que nadie pueda enviar mensajes a tus dispositivos, ninguna estafa de tarifas premium pueda agotar tu saldo y los SMS no puedan utilizarse como vía de ataque contra tu hardware.

Por supuesto, puedes seguir enviando y recibiendo SMS desde tus dispositivos. Los mensajes simplemente pasan por Simbase en lugar de por la red móvil pública. Y ahí es precisamente donde este webhook demuestra toda su potencia.

Cuando tu dispositivo envía un SMS al +55555, ocurren dos cosas:

1. El mensaje aparece en el panel de control de Simbase.

2. Si tienes registrado un webhook de SMS, Simbase reenvía el mensaje completo a través de HTTPS a tu punto final.

Ese segundo paso es la parte que la mayoría de los clientes subestiman. La carga útil contiene el cuerpo del mensaje, el ICCID de la tarjeta SIM, el nombre del dispositivo y una marca de tiempo. Una vez que llega a tu terminal, puedes hacer con ella lo que quieras.

Algunos ejemplos reales de lo que la gente crea con este webhook:

• Reenvía el texto del SMS a un canal de Slack o Microsoft Teams para que el equipo pueda ver los mensajes del dispositivo en tiempo real. Resulta útil para dispositivos de seguimiento de activos, máquinas expendedoras, sensores remotos o cualquier dispositivo que envíe informes por SMS.

• Envía los datos a Zapier o Make.com y activa cualquier acción que admitan esas plataformas: registrar datos en Google Sheets, enviar un correo electrónico, actualizar un CRM, crear un ticket en Zendesk o Intercom, publicar en Notion, etc. No hace falta saber programar.

• Reenvía el SMS a un número de teléfono externo a través de Twilio, MessageBird o cualquier otro proveedor de SMS. Tu dispositivo envía un SMS a través de Simbase, tu webhook lo recibe, tu código reenvía el cuerpo del mensaje a Twilio y Twilio lo entrega a un teléfono móvil convencional. Así es como los clientes crean un puente unidireccional desde una flota de dispositivos IoT aislada hacia un número de teléfono normal, sin renunciar a la seguridad del circuito cerrado.

• Analiza el cuerpo del SMS en busca de lecturas de sensores o comandos y guárdalos en tu propia base de datos o en un almacén de series temporales como InfluxDB o TimescaleDB.

• Activa una acción en la tarjeta SIM. Tu terminal recibe el SMS, determina que «este dispositivo está funcionando de forma anómala» y llama a la API de Simbase para desactivar la tarjeta SIM, limitar su uso o asignarle una política diferente.

Para los lectores que no escriben código, la versión resumida es la siguiente: el webhook de SMS es lo que convierte «ha llegado un SMS a una tarjeta SIM» en «se ha enviado una notificación a Slack», «se ha actualizado la hoja de cálculo», «el equipo ha recibido un correo electrónico» o «se ha abierto un ticket». No hace falta que aprendas cómo funciona el enrutamiento de SMS. Solo tienes que indicar a Simbase la URL correcta. Más información sobre los SMS aquí.

Cuerpo del webhook en formato JSON

{
  "event": "sms",
  "iccid": "8912300000001234567",
  "timestamp": "2022-12-23 12:31:09",
  "message": "test SMS message",
  "deviceName": "Demo device"
}

Cambio de IMEI

Cada dispositivo tiene un IMEI (Identidad Internacional de Equipo Móvil), un identificador único de 15 dígitos integrado en el hardware. Cuando se cambia la tarjeta SIM a otro dispositivo, la red móvil detecta el nuevo IMEI y lo comunica. Simbase puede notificar a tu terminal en el momento en que eso ocurra.

La importancia de esto depende de tu negocio. En el seguimiento de activos, la logística o la gestión de flotas, un cambio inesperado del IMEI es una de las señales más claras de que se ha extraído una tarjeta SIM del dispositivo al que estaba destinada, ya sea por robo, manipulación o un fallo en el mantenimiento. Para los fabricantes de equipos originales (OEM) que envían dispositivos preconfigurados, los eventos de cambio de IMEI son la forma de confirmar que cada tarjeta SIM ha acabado en el dispositivo al que estaba destinada.

Lo que suele hacerse con este webhook:

• Publica el incidente en Slack o envíalo por correo electrónico para que tu equipo de operaciones pueda investigarlo.

• Abre automáticamente un ticket en tu herramienta de asistencia cuando el nuevo IMEI no coincida con el de un dispositivo esperado.

• Desactiva la tarjeta SIM a través de la API de Simbase si tu política de seguridad considera que los cambios inesperados en el IMEI son un indicio de fraude.

• Registra el cambio en tu base de datos de activos para saber en todo momento qué tarjeta SIM está en cada dispositivo, sin necesidad de realizar una conciliación manual.

• Envía el evento a un SIEM o a un registro de auditoría con fines de cumplimiento normativo y análisis forense.

Cuerpo del webhook en formato JSON

{
  "event": "imei",
  "timestamp": "2022-12-23 12:34:07",
  "iccid": "8912300000001234567",
  "oldIMEI": "None",
  "newIMEI": "355234090012345",
  "action": "disabled",
  "deviceName": "Demo device"
}

Cambios en el estado de la tarjeta SIM

Una tarjeta SIM tiene un estado que indica si está activada, desactivada, suspendida, etc. Este estado puede cambiar por varias razones:

• Activación o desactivación manual a través del panel de control o de la API

• Activación automática la primera vez que se utiliza la tarjeta SIM

• Saldo agotado

• Incidentes como robos o presuntos fraudes

• Cambios en el IMEI que activan una política

Cuando cambia el estado, Simbase envía el nuevo estado a tu webhook para que el resto de tu pila pueda reaccionar. Más información sobre los estados de SIM aquí.

Lo que suelen hacer los clientes ante esta situación:

• Mantén sincronizada una base de datos interna de CRM, ERP o de activos con el estado real de cada tarjeta SIM, sin necesidad de consultar la API de Simbase.

• Recibe una notificación por Slack o por correo electrónico en cuanto se desactive una tarjeta SIM, para que el equipo de atención al cliente se entere antes de que el cliente llame.

• Activa la automatización de la facturación cuando se active una tarjeta SIM por primera vez, enviando el evento a Stripe, Chargebee o un servicio de facturación personalizado a través de Zapier o tu propio sistema de backend.

• Detecta las sorpresas a tiempo. Si se ha desactivado una tarjeta SIM y nadie de tu equipo se lo esperaba, considéralo automáticamente como un incidente.

Cuerpo del webhook en formato JSON

{
  "event": "sim_state",
  "timestamp": "2022-12-23 12:42:57",
  "iccid": "8912300000001234567",
  "old_state": "enabled",
  "new_state": "disabled",
  "deviceName": "Demo device"
}

Limitación de velocidad

Puedes configurar políticas de tráfico en el panel de control de Simbase para limitar automáticamente la velocidad de datos de una tarjeta SIM cuando su consumo mensual supere el umbral que elijas. Cuando se limita la velocidad de una tarjeta SIM, Simbase puede activar un webhook para que no te enteres de ello a través de un cliente insatisfecho.

Algunas acciones útiles que puedes realizar una vez que el evento llegue a tu punto final:

• Envía un correo electrónico o un mensaje de texto al propietario del dispositivo con un mensaje claro: «Tu dispositivo tiene la velocidad limitada a 100 KB/s hasta finales de mes».

• Introduce una ficha en tu herramienta de asistencia para que el equipo esté preparado cuando se reciba una queja por «conexión lenta».

• Actualiza el panel de control para clientes, de modo que el cliente pueda ver exactamente cuándo se activó el limitador de velocidad.

• Activa un proceso de venta adicional o de mejora del plan si un cliente sigue alcanzando el límite.

• Envía el evento a Slack para que el equipo de ingeniería pueda ver en tiempo real los patrones de limitación de tráfico en toda la flota.

Cuerpo del webhook en formato JSON

{
  "event": "throttle",
  "timestamp": "2022-12-23 13:10:15",
  "iccid": "8912300000001234567",
  "speedKBps": 100
}

El uso supera el umbral

Aunque no se haya configurado ninguna política de tráfico, se puede activar un webhook cuando el consumo mensual de datos de una tarjeta SIM supere un umbral fijo.

Esta es una forma eficaz de detectar a tiempo un dispositivo que no funciona correctamente. Una tarjeta SIM que normalmente consume 10 MB al mes y de repente supera los 100 MB suele estar intentando indicarte algo: un error de firmware, una conexión de reserva a Wi-Fi que ha fallado, un dispositivo que se ha quedado en modo de depuración, una actualización OTA descontrolada o, en el peor de los casos, una tarjeta SIM robada que se está utilizando para compartir conexión.

Cosas que los clientes suelen hacer con este evento:

• Enviar una alerta a Slack o por correo electrónico cuando una tarjeta SIM supere el límite establecido,

• Abre una incidencia en PagerDuty u Opsgenie para las implementaciones de alta prioridad.

• Limitar o desactivar la tarjeta SIM automáticamente a través de la API de Simbase.

• Activa un flujo de Zapier o Make.com que envíe una notificación al propietario del dispositivo antes de que aumente la factura.

• Registra el evento en un panel de control de anomalías de uso para poder detectar las tendencias generales de la flota a lo largo del tiempo.

Cuerpo del webhook JSON cuando el uso supera los 100 MB

{
  "event": "limit.100mb",
  "timestamp": "2022-12-23 13:13:24",
  "iccid": "8912300000001234567",
  "usageBytes": 104857600,
  "usageMegaBytes": 100,
  "deviceName": "Demo device"
}

Pasos para recibir webhooks

Puedes empezar a recibir notificaciones de eventos en tu aplicación en unos pocos pasos:

1. Decide qué eventos quieres monitorizar y qué campos de la carga útil te interesan realmente.

2. Crea un punto final HTTP(S) para recibir los eventos. Puede tratarse de una ruta en tu backend, una función sin servidor, una URL de webhook de Zapier, una URL de webhook de Make.com, un webhook entrante de Slack (con una pequeña transformación previa) o cualquier otra URL que acepte solicitudes POST.

3. Analiza el cuerpo JSON por tu cuenta y devuelve un código de estado 2xx. Para Simbase solo importa el código de estado, no el cuerpo de la respuesta.

4. Prueba el punto final con una herramienta como Cartero o curl. Si quieres recibir eventos reales de Simbase mientras desarrollas en tu portátil, una herramienta de túnel como ngrok o Cloudflare Tunnel funciona bien.

5. Implementa tu punto final detrás de una URL HTTPS accesible públicamente.

6. Registra esa URL en el Panel de control de Simbase en la sección «Integraciones».

7. Simbase envía un evento de prueba a tu URL. Si tu punto final responde con un código 2xx, el webhook se guarda y comienza a recibir eventos en tiempo real.

Especificaciones

Método

Todas las llamadas de Simbase a tu webhook son solicitudes HTTP POST con un cuerpo en formato JSON.

Seguridad

• Cada llamada lleva un encabezado denominado x-simbase-requesttoken. En las llamadas de prueba, el valor es prueba-prueba-prueba-prueba-prueba. Utiliza este encabezado en tu sistema para confirmar que la solicitud procede realmente de Simbase antes de procesarla.

• No utilices el filtrado de direcciones IP como medida de seguridad. Nuestros servidores están distribuidos por todo el mundo y las direcciones IP públicas desde las que envían datos cambian con el tiempo, por lo que una lista de direcciones IP permitidas dejará de funcionar en el peor momento posible.