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.

Usi già i webhook?Non cambierà nulla. I webhook legacy continueranno a funzionare per il prossimo futuro, ma non riceveranno nuove funzionalità. Assicurati di utilizzare Events per qualsiasi nuova funzionalità.

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 POST richiesta.

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_id che 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
  • simcard.sms.mo
  • simcard.sms.mt
  • simcard.security.imei_changed
  • simcard.state.enabled
  • simcard.state.disabled
  • simcard.usage.threshold_exceeded
  • simcard.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.

Non esagerare con i CDRsimcard.usage.cdr è di gran lunga il tipo di evento più frequente: una SIM attiva può generare molti record al giorno. Un filtro su simcard o simcard.usage lo include. Includi i CDR solo se memorizzi o elabori effettivamente i record di utilizzo e assicurati che il tuo endpoint sia in grado di gestire tale volume.

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:

{
"event_type": "simcard.sms.mo",
"event_id": "01KPX0BH46PVJ89YE6446Q086M",
"timestamp": "2026-11-13T09:30:12.418000Z",
"correlation_id": "123e4567-e89b-12d3-a456-426614174001",
"customer_id": "C123123123123",
"event": {
"iccid": "8900000000001234567",
"message": "temp=21.4;door=closed",
"timestamp": "2026-11-13T09:30:11Z"
}
}

A cosa serve ogni campo della busta:

  • tipo_evento ti indica di quale evento si tratta e, di conseguenza, quali campi sono presenti in evento.

  • 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_id collega 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

{
"event": {
"iccid": "8900000000001234567",
"imei_old": "356938035643021",
"imei_new": "356938035643039",
"imei_lock": "off"
}
}

Soglia di utilizzo superata (utilizzo in byte, la soglia è null (se non è impostato)

{
"event": {
"iccid": "8900000000001234567",
"usage_data": 105906176,
"usage_sms": 3,
"threshold_data": 104857600,
"threshold_sms": null
}
}

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

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. Rispondi in fretta. Il tuo endpoint dovrebbe restituire un 2xx verificare lo stato non appena arriva la richiesta e svolgere il lavoro vero e proprio in un secondo momento.

  6. Verifica la firma prima di reagire a un evento. Vedi Sicurezza.

  7. 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-timestamp e firma del webhook, utilizzato per verificare la richiesta

  • X-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_id per 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 ora quando l'ordine è importante, ad esempio in caso di cambiamenti di stato.

  • Cosa si intende per successo: qualsiasi 2xx codice di stato.

  • Nuovo tentativo con un intervallo di attesa fino a 4 ore: timeout, 408, 429 e 5xx risposte. A Retry-After L'intestazione viene rispettata.

  • Non riprovato: qualsiasi altro codice di stato, reindirizzamenti inclusi.

  • Sospesi con effetto immediato: a 410 Esaurito La 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.

FidelizzazioneGli eventi vengono conservati per 30 giorni. I tentativi di consegna rimangono visibili per 15 giorni.

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
  • 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 evento campo, 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 precedente e nuovo_stato campi.

  • 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:

  1. Aggiungi una destinazione per gli stessi tipi di evento, indicando un nuovo percorso sul tuo endpoint.

  2. Aggiorna il tuo codice per leggere il nuovo payload e verificare la firma.

  3. 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.

  4. 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