Events: notifiche in tempo reale dalle tue SIM
Gli eventi segnalano ai tuoi sistemi ogni volta che si verifica qualcosa sulle SIM Simbase. Quando un dispositivo invia un SMS, una SIM viene inserita in un nuovo dispositivo, una SIM viene disattivata o viene superato un limite di utilizzo, Simbase invia i dettagli a un URL da te scelto in pochi secondi, così non dovrai mai interrogare l'API per scoprirlo.
Gli eventi sostituiscono i webhook tradizionali. Coprono le stesse situazioni e aggiungono alcune funzionalità richieste dai clienti: più tipi di eventi, un’unica destinazione per diversi tipi di eventi, richieste firmate verificabili, un registro delle consegne e un numero maggiore di tentativi di consegna.
Sei pronto per andare in onda? Aggiungi una destinazione nella pagina "Integrazioni" della dashboard.
Come funzionano gli eventi
Due idee bastano a spiegare tutto:
Un evento è una registrazione di un evento verificatosi, ad esempio "La SIM 8900…567 ha inviato un SMS". Ogni evento ha un tipo, un ID univoco, un timestamp e i dettagli specifici del proprio tipo.
Una destinazione è il luogo in cui vengono inviati gli eventi. Oggi si tratta di un webhook: un URL HTTPS che riceve ogni evento in formato JSON
POSTrichiesta.
Quando si verifica un evento, Simbase lo invia a tutte le destinazioni il cui filtro corrisponde al tipo dell'evento. Il tuo endpoint risponde con un 2xx codice di stato.
L'URL può essere qualsiasi indirizzo che accetti una richiesta POST tramite HTTPS:
Una piattaforma di automazione "no-code" come Zapier o Make.com
Uno strumento di chat di gruppo come Slack o Microsoft Teams (di solito con Zapier o Make.com come intermediario per modificare il messaggio)
Un percorso sul tuo backend, in qualsiasi linguaggio
Una funzione serverless su AWS Lambda, Vercel, Cloudflare Workers, Google Cloud Functions e piattaforme simili
Cosa c'è di nuovo rispetto ai webhook
Altri tipi di eventi. Oltre ai quattro eventi storici, sono ora disponibili gli SMS inviati a una SIM e ogni nuovo record di utilizzo (CDR).
Una destinazione, tanti eventi. Un webhook legacy supportava un solo tipo di evento. Il filtro di una destinazione può includere tutti i tipi di evento che si desidera, oppure tutti quanti.
Richieste firmate. Ogni richiesta è accompagnata da una firma, in modo che il tuo endpoint possa verificare che provenga effettivamente da Simbase e che non sia stata alterata durante il trasferimento.
A prova di duplicati. Ogni evento ha un codice univoco
event_idche rimane invariato a ogni tentativo di consegna.Tentativi di ricollegamento più lunghi. Le consegne non andate a buon fine vengono riprovate con un backoff della durata massima di 4 ore, anziché con tre tentativi.
Registro delle consegne. È possibile visualizzare i tentativi di consegna degli ultimi 15 giorni per ciascuna destinazione, compresi quelli non andati a buon fine.
Il sondaggio come soluzione di ripiego. Gli eventi vengono conservati per 30 giorni e possono essere consultati anche tramite l'API, senza una destinazione specifica.
Tipi di eventi
I nomi dei tipi di evento sono composti da parti separate da punti, dalla più generica alla più specifica, come ad esempio simcard.sms.mo. Un filtro può corrispondere a un tipo di evento completo o solo all'inizio del nome, quindi un unico filtro può coprire contemporaneamente diversi tipi di eventi correlati.
Gli eventi SMS utilizzano la terminologia standard del settore della telefonia mobile. MO (inviato da cellulare) è un SMS inviato dalla SIM, dal dispositivo a Simbase. MT (con destinazione mobile) è un SMS inviato alla SIM, dalla dashboard o tramite l'API al dispositivo.
| Tipo di evento | Inviato quando |
|---|---|
| Un dispositivo invia un SMS dalla SIM a Simbase (MO, originato dal cellulare) |
| Viene inviato un SMS alla SIM, dalla dashboard o tramite l'API (MT, mobile terminated) |
| È stata rilevata una SIM in un dispositivo con un IMEI diverso |
| La SIM è attiva |
| Una SIM è disattivata |
| Una SIM supera una soglia stabilita nei propri limiti di utilizzo |
| Viene creato un nuovo record di utilizzo (CDR) per una SIM |
simcard.sms.mosimcard.sms.mtsimcard.security.imei_changedsimcard.state.enabledsimcard.state.disabledsimcard.usage.threshold_exceededsimcard.usage.cdr
Filtraggio degli eventi
Quando si crea una destinazione, è il suo filtro a determinare quali dati riceve:
Un unico tipo di evento, come
simcard.state.disabled, per "avvisami quando una SIM si disconnette".Un prefisso, come
simcard.sms, per ogni tipo di evento che inizia con esso. In questo caso, si tratta sia degli SMS MO che di quelli MT.Tutto: lasciare il filtro vuoto per ricevere tutti i tipi di evento.
Cosa si realizza con gli eventi
SMS provenienti da dispositivi (MO): inoltrare i messaggi del dispositivo su Slack o Teams, registrarli in un foglio di lavoro Google tramite Zapier, analizzare i dati dei sensori e inserirli nel database oppure inoltrarli a un numero di telefono tramite Twilio. Vedi SMS.
SMS ai dispositivi (MT): confermare che un SMS contenente un comando o una configurazione sia stato inviato a un dispositivo e tenere un registro di ciò che è stato inviato.
IMEI modificato: inviare un avviso o aprire un ticket quando una SIM viene rilevata in un dispositivo non previsto, oppure disattivarla tramite l'API. L'evento include lo stato di protezione antifurto della SIM, in modo da poter verificare se la modifica è stata bloccata.
SIM abilitata o disabilitata: mantieni sincronizzati il tuo CRM o il database delle risorse, avvisa l’assistenza prima che il cliente chiami oppure avvia la fatturazione quando una SIM diventa attiva. Vedi Stato della SIM.
Soglia di utilizzo superata: individuare tempestivamente un dispositivo fuori controllo, aprire un incidente su PagerDuty o avvisare il proprietario del dispositivo. Vedi Limiti di utilizzo.
CDR: integrare i dati sull'utilizzo nella propria fatturazione o nei propri strumenti di analisi, anziché esportarli.
Come si presenta un evento
Ogni richiesta ha la stessa struttura esterna, ovvero la busta, con i dettagli dell'evento all'interno del evento campo. Ecco un SMS inviato da un dispositivo:
A cosa serve ogni campo della busta:
tipo_eventoti indica di quale evento si tratta e, di conseguenza, quali campi sono presenti inevento.event_idè un valore unico per questo evento e rimane lo stesso ad ogni nuovo tentativo. Utilizzalo per ignorare i duplicati.data e oraè l'ora in cui Simbase ha registrato l'evento, in UTC (RFC 3339).correlation_idcollega l'evento alla causa che lo ha provocato. Inseriscilo quando contatti l'assistenza in merito a un evento.id_clienteè il tuo account Simbase.
Solo il evento Le parti variano a seconda del tipo. Altri due esempi:
IMEI modificato
Soglia di utilizzo superata (utilizzo in byte, la soglia è null (se non è impostato)
Gli altri tipi seguono lo stesso schema. Gli eventi relativi allo stato della SIM contengono il iccid. I CDR contengono l'ora di inizio e di fine, il tipo, il volume e la rete (MCC e MNC). L'elenco completo dei campi per ogni tipo è riportato nel Riferimento API.
Imposta una destinazione
Decidi di cosa hai bisogno. Quali tipi di eventi e quali campi al loro interno intendi utilizzare. Inizia con poco; potrai modificare il filtro in un secondo momento.
Ottieni un URL HTTPS che accetti richieste POST: una route nel tuo backend, una funzione serverless oppure un URL di webhook di Zapier o Make.com. Deve essere raggiungibile da Internet pubblico.
Aggiungi la destinazione. Nel cruscotto, apri Integrazioni e aggiungi una nuova destinazione. Inserisci l'URL, assegnagli un nome che ti sia familiare e imposta il Filtro ai tipi di evento desiderati.
Salva il segreto di firma. Il dashboard mostra un segreto che inizia con
whsec_. Viene visualizzato una sola volta, quindi conservalo in un posto sicuro, ad esempio nel tuo gestore di password o nell'archivio dei segreti della tua app.Rispondi in fretta. Il tuo endpoint dovrebbe restituire un
2xxverificare lo stato non appena arriva la richiesta e svolgere il lavoro vero e proprio in un secondo momento.Verifica la firma prima di reagire a un evento. Vedi Sicurezza.
Controlla il registro delle consegne per i primi eventi, per verificare che arrivino e che il tuo endpoint risponda con
2xx.
È inoltre possibile creare e gestire le destinazioni tramite il API, utilizzando una chiave API con gli ambiti di integrazione.
Specifiche tecniche
Metodo e intestazioni
Ogni consegna avviene tramite HTTPS POST con un corpo JSON, inviata esclusivamente a indirizzi IP pubblici. Ogni richiesta include le seguenti intestazioni:
webhook-id,webhook-timestampefirma del webhook, utilizzato per verificare la richiestaX-Simbase-Integrazione-ID, la destinazione a cui è stata inviata la richiesta
Sicurezza
Le richieste vengono firmate secondo la procedura aperta Webhook standard specifiche. Simbase firma ogni richiesta con il tuo whsec_ segreto e inserisce il risultato nel firma del webhook intestazione. Verificarla dimostra che la richiesta proviene da Simbase e non è stata manomessa.
Il modo più semplice è uno di quelli gratuiti Librerie standard per i webhook, disponibile per la maggior parte delle lingue: basta passare il corpo della richiesta non elaborato, le intestazioni e la propria chiave segreta, e la libreria si occuperà del resto, compreso il rifiuto delle richieste obsolete. Il Riferimento API contiene anche un breve esempio per verificarlo senza ricorrere a una libreria.
Due cose da tenere a mente:
Controlla il corpo grezzo. Verifica la firma rispetto al contenuto esattamente così come è stato ricevuto, prima che il tuo framework analizzi o riformatti il JSON.
Non fare affidamento sulle liste di indirizzi IP autorizzati. I server di Simbase sono distribuiti in tutto il mondo e gli indirizzi da cui inviano i messaggi cambiano nel tempo. La firma rappresenta il metodo di verifica affidabile.
Se invii eventi a uno strumento "no-code" che non è in grado di verificare le firme, considera l'URL stesso come un dato riservato e non condividerlo.
Se il tuo server utilizza un certificato TLS autofirmato, puoi disattivare la verifica del certificato per quella destinazione.
Consegna e tentativi di consegna
Almeno una volta. Un evento può verificarsi più di una volta. Utilizza
event_idper ignorare le ripetizioni.Non sempre in ordine. Gli eventi potrebbero essere visualizzati in un ordine diverso da quello in cui si sono verificati. Ordina per
data e oraquando l'ordine è importante, ad esempio in caso di cambiamenti di stato.Cosa si intende per successo: qualsiasi
2xxcodice di stato.Nuovo tentativo con un intervallo di attesa fino a 4 ore: timeout,
408,429e5xxrisposte. ARetry-AfterL'intestazione viene rispettata.Non riprovato: qualsiasi altro codice di stato, reindirizzamenti inclusi.
Sospesi con effetto immediato: a
410 EsauritoLa risposta sospende la destinazione.Sospeso dopo 48 ore: una destinazione che continua a generare errori per 48 ore consecutive viene sospesa. Per ricominciare a ricevere nuovi eventi, riattivala dalla dashboard o tramite l'API.
Passaggio dai webhook tradizionali
I webhook legacy continuano a funzionare, quindi puoi procedere secondo i tuoi tempi. Ogni evento legacy ha un equivalente diretto:
| Webhook legacy | Tipo di evento |
|---|---|
SMS ricevuto ( |
|
Modifica dell'IMEI ( |
|
Cambiamento di stato della SIM ( |
|
Limiti di utilizzo raggiunti ( |
|
SMS ricevuto (
sms)Modifica dell'IMEI (
IMEI)Cambiamento di stato della SIM (
sim_state)Limiti di utilizzo raggiunti (
limiti_di_utilizzo)
Quali sono le modifiche al carico utile:
I dettagli si spostano all'interno di un
eventocampo, racchiuso nella busta sopra descritta.I timestamp sono in formato RFC 3339, in UTC, come ad esempio
2026-11-13T09:30:12Z.Un cambiamento di stato è ora rappresentato da due tipi di evento, uno per lo stato "abilitato" e uno per lo stato "disabilitato", invece di
stato precedenteenuovo_statocampi.L'utilizzo dei dati è espresso in byte anziché in MB.
Il nome del dispositivo non è indicato. Se necessario, cercalo tramite l'ICCID.
Un modo sicuro per cambiare:
Aggiungi una destinazione per gli stessi tipi di evento, indicando un nuovo percorso sul tuo endpoint.
Aggiorna il tuo codice per leggere il nuovo payload e verificare la firma.
Fai funzionare entrambi in parallelo per qualche giorno e confronta i risultati. Durante questo periodo, ogni modifica verrà applicata due volte: una per ciascun sistema.
Elimina il webhook legacy in Integrazioni → Webhook.
Domande frequenti
No. I webhook legacy continueranno a funzionare per il momento, ma non riceveranno nuove funzionalità. Le nuove integrazioni dovrebbero utilizzare gli eventi.
La consegna avviene almeno una volta, quindi un nuovo tentativo potrebbe arrivare dopo che il tuo endpoint ha già elaborato il primo tentativo. Memorizza il `event_id` degli eventi che hai gestito e salta quelli che hai già visto.
O è tornato `410 Esaurito` oppure non ha funzionato per 48 ore consecutive. Risolvi il problema dell'endpoint, controlla il registro delle consegne per individuare l'errore, quindi riattiva la destinazione nella pagina "Integrazioni". Gli eventi relativi al periodo di sospensione non vengono reinviati, ma è comunque possibile consultarli tramite l'API per 30 giorni.
Sì, effettuando un sondaggio tramite il API. Le richieste di polling incidono sulla quota API, quindi una destinazione è la scelta migliore per qualsiasi operazione in tempo reale.
Sì. Crea una destinazione per ogni URL, ciascuna con i propri tipi di evento.
No. Il protocollo TLS è obbligatorio per garantire la riservatezza dei dati e la sicurezza delle comunicazioni. Tuttavia, è comunque possibile utilizzare un certificato autofirmato e disabilitare la verifica del certificato TLS sul lato di destinazione.
Correlati
Webhook (versione precedente): il metodo precedente per ricevere gli eventi, ancora supportato
Chiavi API: creare una chiave con gli ambiti necessari per gestire le destinazioni
SMS: i messaggi alla base degli eventi SMS e in che modo variano a seconda del profilo
Protezione antifurto: associare una SIM a un unico IMEI, segnalato negli eventi relativi alla modifica dell'IMEI
Stato della SIM: cosa significano i termini “Abilitato” e “Disabilitato” e cosa li modifica
Limiti di utilizzo: impostare le soglie alla base degli eventi di soglia
API: gestire le destinazioni e interrogare gli eventi a livello di programmazione



