Un webhook è un messaggio che la tua app riceve nel momento stesso in cui si verifica un evento, invece di dover chiedere continuamente "ci sono novità?". Quando si verifica un evento all'interno del tuo account Simbase, Simbase invia tale evento a un URL di tua scelta, 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 riguardano gli eventi che si verificano sul lato di Simbase: SMS in arrivo, modifiche dell'IMEI, cambiamenti dello stato della SIM, limitazioni di banda e soglie 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

• Modifica dello stato della SIM

• Limitazione della velocità

• L'utilizzo supera la soglia

Messaggi SMS ricevuti

Le schede SIM Simbase operano all’interno di quello che chiamiamo un circuito SMS chiuso. In parole povere: la tua 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 è voluto. Si tratta di una misura di sicurezza che rende la tua flotta irraggiungibile dalla rete SMS pubblica, in modo che nessuno possa inviare messaggi ai tuoi dispositivi, nessuna truffa a tariffa maggiorata possa prosciugare il tuo credito e gli SMS non possano essere utilizzati come vettore di attacco contro il tuo hardware.

Ovviamente puoi comunque inviare e ricevere SMS dai tuoi dispositivi. I messaggi passano semplicemente attraverso Simbase anziché attraverso la rete mobile pubblica. Ed è proprio qui che questo webhook dimostra tutta la sua potenza.

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 dispositivo invia un SMS tramite Simbase, il webhook lo riceve, il 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 Simbase per disattivare la SIM, limitarne la velocità o assegnarle una politica diversa.

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. Maggiori informazioni sugli SMS qui.

Corpo del webhook JSON

{
  "event": "sms",
  "iccid": "8912300000001234567",
  "timestamp": "2022-12-23 12:31:09",
  "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 tipo di attività svolta. 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 di 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:

• Pubblica l'evento su Slack o via e-mail, in modo che il tuo 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 si trova in quale dispositivo, senza dover ricorrere a 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": "2022-12-23 12:34:07",
  "iccid": "8912300000001234567",
  "oldIMEI": "None",
  "newIMEI": "355234090012345",
  "action": "disabled",
  "deviceName": "Demo device"
}

Modifiche allo stato della SIM

Una scheda SIM presenta uno stato che indica se è attualmente abilitata, disabilitata, sospesa e così via. 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 sospetti di frode

• Modifiche dell'IMEI che attivano una politica

Quando lo stato cambia, Simbase invia il nuovo stato al tuo webhook in modo che il resto del tuo stack possa reagire. Maggiori informazioni sugli stati SIM qui.

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

• Mantieni un CRM interno, un ERP o un database delle risorse sincronizzato 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": "2022-12-23 12:42:57",
  "iccid": "8912300000001234567",
  "old_state": "enabled",
  "new_state": "disabled",
  "deviceName": "Demo device"
}

Limitazione della velocità

È possibile impostare le politiche di traffico nella dashboard di Simbase per limitare automaticamente la velocità di trasmissione dati di una SIM non appena il suo consumo mensile supera una soglia da voi scelta. Quando la velocità di una SIM viene limitata, Simbase può attivare un webhook in modo che non si venga a sapere la cosa da un cliente insoddisfatto.

Ecco alcune operazioni utili da eseguire una volta che l'evento raggiunge il tuo endpoint:

• Invia un’e-mail o un SMS al proprietario del dispositivo con un messaggio chiaro: “La velocità del tuo dispositivo è limitata a 100 KB/s fino alla fine del mese”.

• Inserisci una scheda nel tuo strumento di supporto, in modo che il team sia pronto nel caso in cui dovesse pervenire un reclamo relativo a una “connessione lenta”.

• Aggiornare la dashboard destinata ai clienti in modo che questi possano vedere esattamente quando è stata attivata la limitazione.

• Attiva un flusso di upsell o di upgrade del piano se un cliente continua a raggiungere il limite massimo.

• Invia l'evento su Slack in modo che il team di ingegneri possa monitorare in tempo reale i modelli di limitazione della banda su tutta la flotta.

Corpo del webhook JSON

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

L'utilizzo supera la soglia

Anche senza impostare una politica di traffico, è possibile attivare un webhook quando il consumo mensile di dati di una SIM supera una soglia prestabilita.

Questo è un metodo efficace per individuare tempestivamente un dispositivo che non funziona correttamente. Una SIM che normalmente consuma 10 MB al mese e improvvisamente supera i 100 MB 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 quando una SIM supera il limite impostato,

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

• Limitare o disattivare automaticamente la SIM tramite l'API Simbase.

• Attiva un flusso su Zapier o Make.com che invii una notifica al proprietario del dispositivo prima che l'importo della fattura aumenti.

• 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 quando l'utilizzo supera i 100 MB

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

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 nella sezione "Integrazioni".

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

• Ogni chiamata contiene un'intestazione denominata x-simbase-requesttoken. Per le chiamate di prova il valore è test-test-test-test-test. Utilizza questa intestazione da parte tua per verificare che la richiesta provenga effettivamente da Simbase prima di darvi seguito.

• 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, pertanto una lista di indirizzi IP autorizzati smetterà di funzionare nel momento peggiore possibile.