Configurare i webhook in Simbase

Un webhook è un messaggio che la tua app riceve nel momento in cui succede qualcosa, invece di dover chiedere di continuo "c'è qualcosa di nuovo?". Quando succede qualcosa nel tuo account Simbase, Simbase invia quell'evento in tempo reale a un URL che controlli tu.

È così che colleghi Simbase al resto del tuo stack. Arriva un SMS su una SIM e il tuo canale Slack riceve una notifica. Un dispositivo cambia IMEI e il tuo sistema di ticketing apre un incidente. Il traffico dati del mese supera una soglia e la tua dashboard dei consumi si aggiorna. Tutto senza scrivere codice che interroga di continuo la nostra API.

I webhook coprono gli eventi che avvengono lato Simbase: SMS in arrivo, cambi di IMEI, cambi di stato della SIM e limiti di utilizzo raggiunti.

Pronto per andare live? Registra il tuo endpoint webhook nella dashboard, così Simbase sa dove consegnare gli eventi.

Come Simbase usa i webhook

Quando succede qualcosa nel tuo account, Simbase esegue un POST HTTPS all'URL che indichi, con un body JSON che descrive l'evento. La tua app legge il body, ne fa quello che vuoi e risponde con un codice di stato 2xx per confermare la ricezione del messaggio.

Non serve costruire niente di complicato sul lato ricevente. L'"URL che indichi" può essere uno di questi:

• Una piattaforma di automazione no-code come Zapier o Make.com

• Uno strumento di chat per team come Slack o Microsoft Teams, tramite i loro URL di incoming webhook integrati (direttamente o con Zapier o Make.com in mezzo)

• Una funzione sul tuo backend, in qualsiasi linguaggio

• Un provider SMS esterno come Twilio o MessageBird, se vuoi inoltrare gli SMS a numeri di telefono pubblici

• Una funzione serverless su AWS Lambda, Vercel, Cloudflare Workers, Google Cloud Functions ecc.

Se puoi darci un URL HTTPS, possiamo inviare gli eventi lì.

Eventi webhook

Simbase supporta i seguenti tipi di evento:

• SMS ricevuti

• Cambio di IMEI

• Cambi di stato della SIM

• Limiti di utilizzo raggiunti

SMS ricevuti

Le SIM con profilo Black, Red e Green funzionano all'interno di quello che chiamiamo circuito SMS chiuso. In pratica: la SIM può inviare SMS al nostro server al numero breve +55555 e ricevere SMS dal nostro server, ma non può scambiare SMS con nessun altro numero al mondo. È voluto. È una misura di sicurezza che rende la tua flotta irraggiungibile dalla rete SMS pubblica: nessuno può scrivere ai tuoi dispositivi, nessuna truffa con numeri a tariffa maggiorata può prosciugare il tuo saldo e gli SMS non possono essere usati per attaccare il tuo hardware.

Le SIM con profilo Blue, Yellow e Cyan hanno un MSISDN, quindi i numeri esterni possono inviare loro SMS. I messaggi inviati da questi dispositivi restano comunque dentro Simbase e non vengono mai consegnati a un telefono esterno, quindi il webhook funziona allo stesso modo su ogni profilo. Vedi SMS per i dettagli di ogni profilo.

Quando il tuo dispositivo invia un SMS al +55555, succedono due cose:

1. Il messaggio diventa visibile nella dashboard di Simbase.

2. Se hai registrato un webhook SMS, Simbase inoltra il messaggio completo via HTTPS al tuo endpoint.

È proprio questo secondo passaggio che la maggior parte dei clienti sottovaluta. Il payload contiene il testo del messaggio, l'ICCID della SIM, il nome del dispositivo e un timestamp. Una volta arrivato al tuo endpoint, puoi farne quello che vuoi.

Alcuni esempi reali di cosa si costruisce con questo webhook:

• Inoltrare il testo dell'SMS a un canale Slack o Microsoft Teams, così il team vede i messaggi dei dispositivi in tempo reale. Utile per tracker, distributori automatici, sensori remoti o qualsiasi dispositivo che comunica via SMS.

• Inviare il payload a Zapier o Make.com e attivare tutto ciò che queste piattaforme supportano: registrare su Google Sheets, inviare un'email, aggiornare un CRM, creare un ticket su Zendesk o Intercom, pubblicare su Notion e così via. Senza codice.

• Inoltrare l'SMS a un numero esterno tramite Twilio, MessageBird o un altro provider SMS. Il tuo dispositivo invia un SMS tramite Simbase, il tuo webhook lo riceve, il tuo codice passa il testo a Twilio e Twilio lo consegna a un normale cellulare. È così che i clienti creano un ponte a senso unico da una flotta IoT blindata a un normale numero di telefono, senza rinunciare alla sicurezza del circuito chiuso.

• Estrarre dal testo dell'SMS letture dei sensori o comandi e salvarli nel tuo database o in un database di serie temporali come InfluxDB o TimescaleDB.

• Avviare un'azione sulla SIM. Il tuo endpoint riceve l'SMS, decide che "questo dispositivo si comporta male" e chiama l'API di Simbase per disattivare la SIM.

Se non scrivi codice, in breve: il webhook SMS trasforma "è arrivato un SMS su una SIM" in "Slack ha ricevuto una notifica", "il foglio di calcolo si è aggiornato", "il team ha ricevuto un'email" o "è stato aperto un ticket". Non devi sapere come funziona l'instradamento degli SMS. Devi solo indicare a Simbase l'URL giusto. Vedi SMS.

Body JSON del webhook

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

Cambio di IMEI

Ogni dispositivo ha un IMEI (International Mobile Equipment Identity), un identificativo univoco di 15 cifre integrato nell'hardware. Quando la tua SIM viene spostata in un altro dispositivo, la rete mobile rileva il nuovo IMEI e lo segnala. Simbase può avvisare il tuo endpoint nel momento stesso in cui succede.

Perché conta dipende dalla tua attività. Nel tracciamento di asset, nella logistica o nella gestione di flotte, un cambio di IMEI inatteso è uno dei segnali più forti che una SIM è stata tolta dal dispositivo previsto, per furto, manomissione o una manutenzione andata storta. Per gli OEM che spediscono dispositivi preconfigurati, gli eventi di cambio IMEI confermano che ogni SIM è finita nel dispositivo giusto.

Cosa si fa di solito con questo webhook:

• Pubblicare l'evento su Slack o inviarlo via email, così il tuo team operativo può verificarlo.

• Aprire automaticamente un ticket nel tuo strumento di assistenza quando il nuovo IMEI non corrisponde a un dispositivo previsto.

• Disattivare la SIM tramite l'API di Simbase se la tua policy di sicurezza considera i cambi di IMEI inattesi un segnale di frode.

• Registrare il cambio nel tuo database degli asset, così sai sempre quale SIM si trova in quale dispositivo, senza riconciliazioni manuali.

• Inviare l'evento a un SIEM o a un log di audit per conformità e analisi 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"
}

Cambi di stato della SIM

Una SIM ha uno stato che indica se è attiva o disattivata. Lo stato può cambiare per diversi motivi:

• Attivazione o disattivazione manuale dalla dashboard o tramite API

• Attivazione automatica al primo utilizzo della SIM

• Saldo esaurito

• Incidenti come furto o sospetta frode

• Cambi di IMEI non autorizzati

Quando lo stato cambia, Simbase invia il nuovo stato al tuo webhook, così il resto del tuo stack può reagire. Vedi Stato della SIM.

Cosa fanno di solito i clienti con questo evento:

• Tenere un CRM, un ERP o un database degli asset interno allineato con lo stato reale di ogni SIM, senza interrogare di continuo l'API di Simbase.

• Ricevere un avviso su Slack o via email appena una SIM viene disattivata, così l'assistenza lo sa prima che chiami il cliente.

• Avviare la fatturazione automatica quando una SIM viene attivata per la prima volta, inviando l'evento a Stripe, Chargebee o a un servizio di fatturazione personalizzato tramite Zapier o il tuo backend.

• Scoprire le sorprese per tempo. Se una SIM è stata disattivata e nessuno nel tuo team se lo aspettava, trattalo automaticamente come un incidente.

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"
}

Limiti di utilizzo raggiunti

Puoi impostare un limite mensile di dati o SMS su qualsiasi SIM. Quando il consumo supera quel limite, Simbase disattiva automaticamente la SIM e questo webhook lo comunica subito al resto del tuo stack.

I limiti vengono verificati quando arrivano i dati di consumo dall'operatore, non in tempo reale, quindi una SIM può superare leggermente il suo limite prima di essere disattivata. Vedi Limiti di utilizzo per capire perché succede e come tenerne conto nel budget.

È un modo pulito per individuare presto un dispositivo che si comporta male. Una SIM che normalmente consuma 10 MB al mese e all'improvviso raggiunge il suo limite di solito ti sta dicendo qualcosa: un bug del firmware, un fallback Wi-Fi andato storto, un dispositivo rimasto in modalità debug, un aggiornamento OTA fuori controllo o, nel caso peggiore, una SIM rubata usata per il tethering.

Cosa si fa di solito con questo evento:

• Inviare un avviso su Slack o via email, così il team sa che una SIM è offline prima che chiami il cliente

• Aprire un incidente su PagerDuty o Opsgenie per i deployment ad alta priorità

• Controllare il dispositivo, poi riattivare la SIM o alzarne il limite tramite l'API di Simbase

• Avviare un flusso Zapier o Make.com che avvisa il proprietario del dispositivo

• Registrare l'evento in una dashboard delle anomalie di consumo per individuare nel tempo le tendenze di tutta la flotta

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
}

Come ricevere i webhook

Puoi iniziare a ricevere notifiche di eventi nella tua app in pochi passaggi:

1. Decidi quali eventi vuoi ascoltare e quali campi del payload ti interessano davvero.

2. Crea un endpoint HTTP(S) per ricevere gli eventi. Può essere una route sul tuo backend, una funzione serverless, un URL webhook di Zapier o Make.com, un incoming webhook di Slack (con una piccola trasformazione davanti) o qualsiasi altro URL che accetti richieste POST.

3. Analizza il body JSON dal tuo lato e restituisci un codice di stato 2xx. Per Simbase conta solo il codice di stato, non il body della risposta.

4. Testa l'endpoint con uno strumento come Postman o curl. Se vuoi ricevere eventi Simbase reali mentre sviluppi sul tuo portatile, uno strumento di tunneling come ngrok o Cloudflare Tunnel funziona bene.

5. Pubblica il tuo endpoint dietro un URL HTTPS raggiungibile pubblicamente.

6. Registra quell'URL nella dashboard di Simbase in Integrations → Webhooks.

7. Simbase invia un evento di test al tuo URL. Se il tuo endpoint risponde con un codice 2xx, il webhook viene salvato e inizia a ricevere eventi reali.

Specifiche

Metodo

Tutte le chiamate di Simbase al tuo webhook sono richieste HTTP POST con un body JSON.

Sicurezza

• Non usare il filtraggio IP come misura di sicurezza. I nostri server sono distribuiti in tutto il mondo e gli IP pubblici da cui inviano cambiano nel tempo, quindi una allowlist di IP si romperà nel momento peggiore.

Domande frequenti

Articoli correlati

• SMS: i messaggi che il webhook degli SMS ricevuti inoltra e come cambiano a seconda del profilo

• Protezione antifurto: blocca una SIM su un IMEI, così un cambio viene impedito e non solo segnalato

• Stato della SIM: cosa significano Attiva e Disattivata e cosa cambia lo stato

• Limiti di utilizzo: imposta il limite che attiva il webhook di utilizzo

• Chiavi API: crea una chiave e limitala a ciò che serve all'integrazione

• API: elenca, crea ed elimina i webhook tramite codice