Un webhook è un messaggio che la tua app riceve nel momento stesso in cui si verifica un evento, senza doverlo richiedere espressamente "Ci sono novità?"" in loop. Quando si verifica un evento all'interno del tuo account Simbase, Simbase invia quell'evento a un URL che puoi controllare in tempo reale.

Ecco come integrare Simbase nel resto del tuo stack. Quando arriva un SMS su una SIM, il tuo canale Slack invia una notifica. Quando un dispositivo cambia IMEI, il tuo sistema di ticketing apre un ticket. Quando il traffico dati mensile supera una soglia, la tua dashboard di utilizzo si aggiorna. Il tutto senza dover scrivere codice per interrogare la nostra API.

I webhook coprono gli eventi che si verificano sul lato di Simbase: SMS in arrivo, modifiche dell'IMEI, cambiamenti dello stato della SIM e limiti di utilizzo.

Sei pronto per andare in diretta? Registra il tuo endpoint webhook nella Dashboard, in modo che Simbase sappia dove inviare gli eventi.

Come Simbase utilizza i webhook

Quando si verifica un evento sul tuo account, Simbase invia una richiesta POST HTTPS all'URL da te specificato, con un corpo JSON che descrive l'evento. La tua app legge il corpo della richiesta, esegue le operazioni che desideri e risponde con un codice di stato 2xx per confermare la ricezione del messaggio.

Non è necessario creare nulla di particolarmente complesso sul lato ricevente. L'"URL specificato" può essere uno qualsiasi dei seguenti:

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

• Uno strumento di chat di gruppo come Slack o Microsoft Teams, utilizzando gli URL dei webhook in entrata integrati (direttamente o tramite Zapier o Make.com)

• Una funzione nel tuo backend, in qualsiasi linguaggio

• Un fornitore di servizi SMS di terze parti come Twilio o MessageBird, se si desidera inoltrare messaggi SMS a numeri di telefono pubblici

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

Se ci fornite un URL HTTPS, possiamo trasmettere gli eventi su quel sito.

Eventi webhook

Simbase supporta i seguenti tipi di eventi:

• Messaggi SMS ricevuti

• Modifiche all'IMEI

• Cambiamento di stato della SIM

• Limiti di utilizzo raggiunti

Messaggi SMS ricevuti

SIM nere, rosse e verdi operano all’interno di quello che chiamiamo un circuito SMS chiuso. In parole povere: 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 di telefono al mondo. Questo è intenzionale. Si tratta di una misura di sicurezza che rende la vostra flotta irraggiungibile dalla rete SMS pubblica, in modo che nessuno possa inviare messaggi ai vostri dispositivi, nessuna truffa a tariffa maggiorata possa prosciugare il vostro credito e gli SMS non possano essere utilizzati come vettore di attacco contro il vostro hardware.

Blu, giallo e ciano Le SIM vengono fornite con un MSISDN, in modo che i numeri esterni possano inviare loro messaggi di testo. I messaggi inviati da tali dispositivi rimangono comunque all’interno di Simbase e non vengono mai recapitati a un telefono esterno, quindi il webhook si comporta allo stesso modo su ogni profilo. Vedi SMS per i dettagli relativi a ciascun profilo.

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

1. Il messaggio viene visualizzato sulla dashboard di Simbase.

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

Quel secondo passaggio è la parte che la maggior parte dei clienti sottovaluta. Il payload contiene il corpo del messaggio, l'ICCID della SIM, il nome del dispositivo e un timestamp. Una volta che arriva sul tuo endpoint, puoi farne ciò che vuoi.

Ecco alcuni esempi concreti di ciò che gli utenti realizzano con questo webhook:

• Inoltra il testo dell'SMS a un canale di Slack o Microsoft Teams in modo che il team possa visualizzare in tempo reale i messaggi provenienti dai dispositivi. Utile per dispositivi di tracciamento delle risorse, distributori automatici, sensori remoti o qualsiasi dispositivo che invii segnalazioni tramite SMS.

• Inserisci i dati in Zapier o Make.com e attiva qualsiasi azione supportata da queste piattaforme: registra i dati su Google Sheets, invia un’e-mail, aggiorna un CRM, crea un ticket su Zendesk o Intercom, pubblica su Notion, ecc. Non è richiesto alcun codice.

• Inoltra l'SMS a un numero di telefono esterno tramite Twilio, MessageBird o qualsiasi altro provider di SMS. Il tuo dispositivo invia un SMS tramite Simbase, il tuo webhook lo riceve, il tuo codice inoltra il contenuto a Twilio e Twilio lo consegna a un normale numero di cellulare. È così che i clienti creano un collegamento unidirezionale da una flotta IoT isolata a un normale numero di telefono, senza rinunciare alla sicurezza del circuito chiuso.

• Analizza il contenuto dell'SMS per individuare i valori dei sensori o i comandi e salvali nel tuo database o in un sistema di archiviazione di serie temporali come InfluxDB o TimescaleDB.

• Attiva un'azione sulla SIM. Il tuo endpoint riceve l'SMS, stabilisce che "questo dispositivo presenta un comportamento anomalo" e chiama l'API di Simbase per disattivare la SIM.

Per i lettori che non scrivono codice, ecco una sintesi: il webhook SMS è ciò che trasforma “un SMS ricevuto su una SIM” in “una notifica inviata su Slack”, “il foglio di calcolo aggiornato”, “un’e-mail inviata al team” o “un ticket aperto”. Non è necessario capire come funziona l’instradamento degli SMS. Basta semplicemente indicare a Simbase l’URL corretto. Vedi SMS.

Corpo del webhook JSON

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

Modifica dell'IMEI

Ogni dispositivo è dotato di un IMEI (International Mobile Equipment Identity), un identificativo univoco di 15 cifre integrato nell'hardware. Quando la SIM viene inserita 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 ciò avviene.

L’importanza di questo aspetto dipende dal proprio settore di attività. Per il tracciamento delle risorse, la logistica o la gestione delle flotte, una modifica imprevista dell’IMEI è uno dei segnali più evidenti che una SIM sia stata rimossa dal dispositivo a cui era destinata, a causa di furto, manomissione o interventi di manutenzione andati male. Per gli OEM che distribuiscono dispositivi preconfigurati, gli eventi relativi alla modifica dell’IMEI consentono di verificare che ogni SIM sia stata inserita nel dispositivo a cui era destinata.

Ecco come viene solitamente utilizzato questo webhook:

• Segnala l'evento su Slack o via e-mail, in modo che il team operativo possa esaminarlo.

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

• Disattiva la SIM tramite l'API Simbase se la tua politica di sicurezza considera le modifiche impreviste dell'IMEI come un segnale di frode.

• Registra la modifica nel database delle risorse, in modo da sapere sempre quale SIM è inserita in quale dispositivo, senza dover effettuare una riconciliazione manuale.

• Inserire l'evento in un sistema SIEM o in un registro di audit a fini di conformità e analisi forense.

Corpo del webhook JSON

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

Modifiche allo stato della SIM

Una scheda SIM presenta uno stato che indica se è attualmente attiva o disattivata. Lo stato può variare per diversi motivi:

• Attivazione o disattivazione manuale tramite la dashboard o l'API

• Attivazione automatica al primo utilizzo della SIM

• Saldo esaurito

• Episodi quali furti o casi di sospetta frode

• Modifiche non autorizzate dell'IMEI

Quando lo stato cambia, Simbase invia il nuovo stato al tuo webhook in modo che il resto del tuo stack possa reagire. Vedi Stato della SIM.

Cosa tendono a fare i clienti in occasione di questo evento:

• Mantieni sincronizzato un database interno CRM, ERP o di gestione delle risorse con lo stato effettivo di ogni SIM, senza dover interrogare l'API di Simbase.

• Ricevi una notifica su Slack o via e-mail non appena una SIM viene disattivata, in modo che l’assistenza ne venga informata prima che il cliente chiami.

• Avvia l'automazione della fatturazione 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.

• Individua tempestivamente gli imprevisti. Se una SIM è stata disattivata e nessuno del tuo team se lo aspettava, consideralo automaticamente un incidente.

Corpo del webhook JSON

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

È possibile impostare un limite mensile di traffico dati o SMS su qualsiasi SIM. Quando l'utilizzo supera tale limite, Simbase disattiva automaticamente la SIM e questo webhook avvisa il resto del tuo stack nel momento stesso in cui ciò accade.

I limiti vengono verificati al momento della ricezione dei dati di utilizzo da parte dell'operatore, anziché in tempo reale; pertanto, una SIM può superare leggermente il proprio limite prima di essere disattivata. Vedi Limiti di utilizzo per capire perché si verifica tale superamento e come prevederlo nel bilancio.

Questo è un metodo efficace per individuare tempestivamente un dispositivo che non funziona correttamente. Una SIM che normalmente consuma 10 MB al mese e improvvisamente raggiunge il limite di traffico di solito sta cercando di segnalarti qualcosa: un bug del firmware, un passaggio al Wi-Fi andato a vuoto, un dispositivo rimasto in modalità debug, un aggiornamento OTA fuori controllo o, nel peggiore dei casi, una SIM rubata utilizzata per il tethering.

Cose che i clienti tendono a fare in occasione di questo evento:

• Invia una notifica su Slack o via e-mail, in modo che il team sappia che una SIM è fuori servizio prima che il cliente chiami

• Apri un ticket in PagerDuty o Opsgenie per le distribuzioni ad alta priorità

• Controlla il dispositivo, quindi riattiva la SIM o aumenta il suo limite tramite l'API Simbase

• Attiva un flusso Zapier o Make.com che invii una notifica al proprietario del dispositivo

• Registra l'evento in una dashboard dedicata alle anomalie di utilizzo, in modo da poter individuare le tendenze a livello di flotta nel corso del tempo

Corpo del webhook JSON

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

Procedura per ricevere i webhook

Per iniziare a ricevere le notifiche relative agli eventi nella tua app bastano pochi passaggi:

1. Decidi quali eventi vuoi monitorare e quali campi del payload ti interessano effettivamente.

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

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

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

5. Configurate il vostro endpoint dietro un URL HTTPS accessibile pubblicamente.

6. Registra quell'URL nel Dashboard di Simbase alla voce Integrazioni → Webhook.

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

Specifiche tecniche

Metodo

Tutte le chiamate inviate da Simbase al tuo webhook sono richieste HTTP POST con un corpo in formato JSON.

Sicurezza

• Non utilizzare il filtraggio degli indirizzi IP come misura di sicurezza. I nostri server sono distribuiti a livello globale e gli indirizzi IP pubblici da cui inviano i dati cambiano nel tempo, quindi una lista di indirizzi IP autorizzati smetterà di funzionare nel momento peggiore possibile.

Domande frequenti

Correlati

• SMS, i messaggi inoltrati dal webhook "SMS ricevuti" e le differenze a seconda del profilo

• Protezione antifurto, bloccare una SIM su un determinato IMEI in modo che la sostituzione sia impedita, non solo segnalata

• Stato della SIM, cosa significano i termini “Abilitato” e “Disabilitato” e cosa li modifica

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

• API, elencare, creare ed eliminare i webhook tramite codice