Configurar webhooks en Simbase

Un webhook es un mensaje que tu app recibe en el momento en que pasa algo, en lugar de tener que preguntar en bucle "¿hay algo nuevo?". Cuando ocurre un evento en tu cuenta de Simbase, Simbase envía ese evento en tiempo real a una URL que tú controlas.

Así conectas Simbase con el resto de tu stack. Llega un SMS a una SIM y tu canal de Slack recibe un aviso. Un dispositivo cambia de IMEI y tu sistema de tickets abre una incidencia. El consumo de datos del mes supera un umbral y tu panel de consumo se actualiza. Todo sin escribir código que consulte nuestra API una y otra vez.

Los webhooks cubren los eventos que ocurren del lado de Simbase: SMS entrantes, cambios de IMEI, cambios de estado de la SIM y límites de uso alcanzados.

¿Listo para ponerlo en marcha? Registra tu endpoint de webhook en el panel para que Simbase sepa adónde enviar los eventos.

Cómo usa Simbase los webhooks

Cuando ocurre algo en tu cuenta, Simbase hace un POST HTTPS a la URL que indiques, con un body JSON que describe el evento. Tu app lee el body, hace con él lo que quieras y responde con un código de estado 2xx para confirmar que recibió el mensaje.

No necesitas construir nada sofisticado del lado receptor. La "URL que indiques" puede ser cualquiera de estas:

• Una plataforma de automatización no-code como Zapier o Make.com

• Una herramienta de chat de equipo como Slack o Microsoft Teams, con sus URL de incoming webhook integradas (directamente o con Zapier o Make.com en medio)

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

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

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

Si nos das una URL HTTPS, podemos enviarle eventos.

Eventos de webhook

Simbase admite estos tipos de evento:

• SMS recibidos

• Cambio de IMEI

• Cambios de estado de la SIM

• Límites de uso alcanzados

SMS recibidos

Las SIM con perfil Black, Red y Green funcionan dentro de lo que llamamos un circuito SMS cerrado. En pocas palabras: la 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 del mundo. Es a propósito. Es una medida de seguridad que mantiene tu flota inaccesible desde la red SMS pública: nadie puede enviar SMS a tus dispositivos, ninguna estafa de tarificación adicional puede vaciar tu saldo y el SMS no puede usarse para atacar tu hardware.

Las SIM con perfil Blue, Yellow y Cyan vienen con un MSISDN, así que los números externos pueden enviarles SMS. Los mensajes que envían esos dispositivos se quedan igualmente dentro de Simbase y nunca se entregan a un teléfono externo, así que el webhook funciona igual en todos los perfiles. Consulta SMS para ver el detalle por perfil.

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

1. El mensaje aparece en el panel de Simbase.

2. Si tienes un webhook de SMS registrado, Simbase reenvía el mensaje completo por HTTPS a tu endpoint.

Ese segundo paso es el que la mayoría de los clientes subestima. El payload incluye el texto del mensaje, el ICCID de la SIM, el nombre del dispositivo y una marca de tiempo. Cuando llega a tu endpoint, puedes hacer con él lo que quieras.

Algunos ejemplos reales de lo que se construye con este webhook:

• Reenviar el texto del SMS a un canal de Slack o Microsoft Teams para que el equipo vea los mensajes de los dispositivos en directo. Útil para rastreadores, máquinas expendedoras, sensores remotos o cualquier dispositivo que informe por SMS.

• Enviar el payload a Zapier o Make.com y activar cualquier cosa que admitan esas plataformas: registrar en Google Sheets, enviar un correo, actualizar un CRM, crear un ticket en Zendesk o Intercom, publicar en Notion, etc. Sin código.

• Reenviar el SMS a un número externo a través de Twilio, MessageBird u otro proveedor de SMS. Tu dispositivo envía un SMS por Simbase, tu webhook lo recibe, tu código pasa el texto a Twilio y Twilio lo entrega en un móvil normal. Así crean los clientes un puente unidireccional entre una flota IoT blindada y un número de teléfono normal, sin renunciar a la seguridad del circuito cerrado.

• Extraer lecturas de sensores o comandos del texto del SMS y guardarlos en tu propia base de datos o en una base de series temporales como InfluxDB o TimescaleDB.

• Lanzar una acción sobre la SIM. Tu endpoint recibe el SMS, decide que "este dispositivo se está comportando mal" y llama a la API de Simbase para desactivar la SIM.

Si no programas, la versión corta es esta: el webhook de SMS convierte "ha llegado un SMS a una SIM" en "Slack ha recibido un aviso", "la hoja de cálculo se ha actualizado", "el equipo ha recibido un correo" o "se ha abierto un ticket". No necesitas saber cómo funciona el enrutamiento de SMS. Solo tienes que darle a Simbase la URL correcta. Consulta SMS.

Body JSON del webhook

{
  "event": "sms",
  "iccid": "8900000000001234567",
  "timestamp": "2026-08-06 12:00:00",
  "message": "test SMS message",
  "deviceName": "Demo device"
}

Cambio de IMEI

Cada dispositivo tiene un IMEI (International Mobile Equipment Identity), un identificador único de 15 dígitos integrado en el hardware. Cuando tu SIM pasa a otro dispositivo, la red móvil detecta el nuevo IMEI y lo comunica. Simbase puede avisar a tu endpoint en ese mismo momento.

Por qué importa depende de tu negocio. En seguimiento de activos, logística o gestión de flotas, un cambio de IMEI inesperado es una de las señales más claras de que una SIM se ha sacado de su dispositivo previsto, ya sea por robo, manipulación o un mantenimiento que salió mal. Para los OEM que envían dispositivos preaprovisionados, los cambios de IMEI sirven para confirmar que cada SIM acabó en el dispositivo correcto.

Lo que se suele hacer con este webhook:

• Publicar el evento en Slack o enviarlo por correo para que tu equipo de operaciones lo revise.

• Abrir automáticamente un ticket en tu herramienta de soporte cuando el nuevo IMEI no coincide con ningún dispositivo esperado.

• Desactivar la SIM con la API de Simbase si tu política de seguridad trata los cambios de IMEI inesperados como señal de fraude.

• Registrar el cambio en tu base de datos de activos para saber siempre qué SIM está en qué dispositivo, sin conciliaciones manuales.

• Enviar el evento a un SIEM o a un registro de auditoría para cumplimiento normativo y análisis forense.

Body JSON del webhook

{
  "event": "imei",
  "timestamp": "2026-08-06 12:00:00",
  "iccid": "8900000000001234567",
  "oldIMEI": "None",
  "newIMEI": "355234090012345",
  "action": "disabled",
  "deviceName": "Demo device"
}

Cambios de estado de la SIM

Una SIM tiene un estado que indica si está activada o desactivada. El estado puede cambiar por varios motivos:

• Activación o desactivación manual desde el panel o la API

• Activación automática al usar la SIM por primera vez

• Saldo agotado

• Incidentes como robo o sospecha de fraude

• Cambios de IMEI no autorizados

Cuando cambia el estado, Simbase envía el nuevo estado a tu webhook para que el resto de tu stack pueda reaccionar. Consulta Estado de la SIM.

Lo que suelen hacer los clientes con este evento:

• Mantener un CRM, ERP o base de datos de activos interna sincronizada con el estado real de cada SIM, sin consultar la API de Simbase una y otra vez.

• Recibir una alerta en Slack o por correo en cuanto se desactiva una SIM, para que soporte se entere antes de que llame el cliente.

• Iniciar la facturación automática cuando una SIM se activa por primera vez, enviando el evento a Stripe, Chargebee o un servicio de facturación propio a través de Zapier o tu propio backend.

• Detectar sorpresas a tiempo. Si una SIM se ha desactivado y nadie de tu equipo lo esperaba, trátalo automáticamente como una incidencia.

Body JSON del webhook

{
  "event": "sim_state",
  "timestamp": "2026-08-06 12:00:00",
  "iccid": "8900000000001234567",
  "old_state": "enabled",
  "new_state": "disabled",
  "deviceName": "Demo device"
}

Límites de uso alcanzados

Puedes fijar un límite mensual de datos o de SMS en cualquier SIM. Cuando el consumo supera ese límite, Simbase desactiva la SIM automáticamente y este webhook avisa al resto de tu stack en ese momento.

Los límites se comprueban cuando llegan los registros de consumo del operador, no en tiempo real, así que una SIM puede pasarse ligeramente de su límite antes de desactivarse. Consulta Límites de uso para saber por qué ocurre y cómo tenerlo en cuenta en tu presupuesto.

Es una forma limpia de detectar pronto un dispositivo que falla. Una SIM que normalmente consume 10 MB al mes y de repente alcanza su límite suele estar avisándote de algo: un fallo de firmware, un respaldo por Wi-Fi que salió mal, un dispositivo que se quedó en modo debug, una actualización OTA descontrolada o, en el peor caso, una SIM robada que se usa para compartir conexión.

Lo que se suele hacer con este evento:

• Enviar una alerta a Slack o por correo, para que el equipo sepa que una SIM está desconectada antes de que llame el cliente

• Abrir una incidencia en PagerDuty u Opsgenie en despliegues de alta prioridad

• Revisar el dispositivo y después reactivar la SIM o subir su límite con la API de Simbase

• Lanzar un flujo de Zapier o Make.com que avise al propietario del dispositivo

• Registrar el evento en un panel de anomalías de consumo para detectar con el tiempo tendencias en toda la flota

Body JSON del webhook

{
  "event": "usage_limits",
  "timestamp": "2026-08-06 12:00:00",
  "iccid": "8900000000001234567",
  "usage_mb": 102,
  "threshold_mb": 100,
  "usage_sms": 0,
  "threshold_sms": null
}

Pasos para recibir webhooks

Puedes empezar a recibir notificaciones de eventos en tu app en pocos pasos:

1. Decide qué eventos quieres escuchar y qué campos del payload te interesan de verdad.

2. Crea un endpoint HTTP(S) para recibir los eventos. Puede ser una ruta en tu backend, una función serverless, una URL de webhook de Zapier o Make.com, un incoming webhook de Slack (con una pequeña transformación delante) o cualquier otra URL que acepte peticiones POST.

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

4. Prueba el endpoint con una herramienta como Postman 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. Despliega tu endpoint detrás de una URL HTTPS accesible públicamente.

6. Registra esa URL en el panel de Simbase en Integrations → Webhooks.

7. Simbase envía un evento de prueba a tu URL. Si tu endpoint responde con un código 2xx, el webhook se guarda y empieza a recibir eventos reales.

Especificaciones

Método

Todas las llamadas de Simbase a tu webhook son peticiones HTTP POST con un body JSON.

Seguridad

• No uses el filtrado por IP como medida de seguridad. Nuestros servidores están distribuidos por todo el mundo y las IP públicas desde las que envían cambian con el tiempo, así que una lista de IP permitidas fallará en el peor momento.

Preguntas frecuentes

Artículos relacionados

• SMS: los mensajes que reenvía el webhook de SMS recibidos y cómo cambian según el perfil

• Protección antirrobo: vincula una SIM a un IMEI para que un cambio se bloquee y no solo se notifique

• Estado de la SIM: qué significan Activada y Desactivada y qué cambia el estado

• Límites de uso: fija el límite que activa el webhook de uso

• Claves de API: crea una clave y limítala a lo que necesita la integración

• API: lista, crea y elimina webhooks desde código