Events : notifications en temps réel de vos SIM
Les événements informent vos systèmes dès qu'un incident survient sur vos cartes SIM Simbase. Qu'il s'agisse de l'envoi d'un SMS par un appareil, de l'insertion d'une carte SIM dans un nouvel appareil, de la désactivation d'une carte SIM ou du dépassement d'une limite d'utilisation : Simbase transmet ces informations à l'URL de votre choix en quelques secondes, vous évitant ainsi d'avoir à interroger l'API pour les obtenir.
Les événements remplacent les webhooks traditionnels. Ils couvrent les mêmes cas de figure et apportent quelques améliorations demandées par les clients : davantage de types d'événements, une destination unique pour plusieurs types d'événements, des requêtes signées que vous pouvez vérifier, un journal de livraison et des délais de réessai plus longs.
Prêt à mettre en ligne ? Ajouter une destination sur la page « Intégrations » du tableau de bord.
Fonctionnement des événements
Deux idées suffisent pour tout couvrir :
Un événement Il s'agit d'un enregistrement d'un événement qui s'est produit, par exemple « La carte SIM 8900…567 a envoyé un SMS ». Chaque événement possède un type, un identifiant unique, un horodatage et les détails propres à son type.
Une destination C'est là que les événements sont envoyés. Aujourd'hui, il s'agit d'un webhook : une URL HTTPS qui reçoit chaque événement au format JSON
PUBLICATIONdemande.
Lorsqu'un événement se produit, Simbase l'envoie à toutes les destinations dont le filtre correspond à son type. Votre point de terminaison répond par un 2xx code d'état.
L'URL peut être n'importe quelle adresse acceptant une requête POST via HTTPS :
Une plateforme d'automatisation sans code, comme Zapier ou Make.com
Un outil de discussion d'équipe comme Slack ou Microsoft Teams (généralement associé à Zapier ou Make.com pour reformuler le message)
Une route sur votre propre backend, quel que soit le langage utilisé
Une fonction « serverless » sur AWS Lambda, Vercel, Cloudflare Workers, Google Cloud Functions et autres plateformes similaires
Quelles sont les nouveautés par rapport aux webhooks ?
Davantage de types d'événements. Les SMS envoyés vers une carte SIM et chaque nouvel enregistrement d'utilisation (CDR) sont désormais disponibles, en plus des quatre événements existants.
Une seule destination, de nombreux événements. Un webhook hérité ne prenait en charge qu'un seul type d'événement. Le filtre d'une destination peut inclure autant de types d'événements que vous le souhaitez, voire tous.
Demandes signées. Chaque requête est accompagnée d'une signature, ce qui permet à votre point de terminaison de vérifier qu'elle provient bien de Simbase et qu'elle n'a pas été altérée en cours de route.
Sans risque de doublons. Chaque événement possède un
event_idqui reste le même à chaque tentative de livraison.Des tentatives de reconnexion plus longues. Les livraisons ayant échoué font l'objet de nouvelles tentatives avec un délai d'attente pouvant aller jusqu'à 4 heures, au lieu de trois tentatives.
Registre des livraisons. Vous pouvez consulter les tentatives de livraison des 15 derniers jours pour chaque destination, y compris celles qui ont échoué.
Le polling comme solution de secours. Les événements sont conservés pendant 30 jours et peuvent également être consultés via l'API, sans destination.
Types d'événements
Les noms des types d'événements sont composés d'éléments séparés par des points, allant du plus général au plus spécifique, comme par exemple simcard.sms.mo. Un filtre peut correspondre à un type d'événement complet ou simplement au début de son nom ; ainsi, un seul filtre peut couvrir plusieurs types d'événements liés à la fois.
Les événements par SMS utilisent la terminologie standard de la téléphonie mobile. MO (provenant d'un mobile) désigne un SMS envoyé par la carte SIM, depuis l'appareil vers Simbase. MT (destinataire mobile) désigne un SMS envoyé à la carte SIM, depuis le tableau de bord ou l'API, vers l'appareil.
| Type d'événement | Envoyé le |
|---|---|
| Un appareil envoie un SMS depuis la carte SIM vers Simbase (MO, message provenant d'un mobile) |
| Un SMS est envoyé vers la carte SIM, depuis le tableau de bord ou via l'API (MT, « mobile terminated ») |
| Une carte SIM a été détectée dans un appareil dont l'IMEI est différent. |
| Une carte SIM est activée |
| Une carte SIM est désactivée |
| Une carte SIM dépasse un seuil défini dans ses limites d'utilisation |
| Un nouvel enregistrement de données d'utilisation (CDR) est créé pour une carte SIM |
simcard.sms.mosimcard.sms.mtsimcard.security.imei_changedsimcard.state.enabledsimcard.state.disabledsimcard.usage.threshold_exceededsimcard.usage.cdr
Filtrage des événements
Lorsque vous créez une destination, c'est son filtre qui détermine ce qu'elle reçoit :
Un seul type d'événement, comme
carte SIM.état.désactivée, pour « m'avertir lorsqu'une carte SIM se déconnecte ».Un préfixe, comme
carte SIM.SMS, pour chaque type d'événement commençant par ces lettres. Dans ce cas précis, il s'agit à la fois des SMS MO et MT.Tout: laissez le filtre vide pour recevoir tous les types d'événements.
Ce que les gens créent grâce à Events
SMS provenant d'appareils (MO) : transférer les messages de l'appareil vers Slack ou Teams, les enregistrer dans une feuille Google Sheet via Zapier, analyser les données des capteurs et les intégrer à votre base de données, ou les transmettre à un numéro de téléphone via Twilio. Voir SMS.
SMS vers des appareils (MT) : vérifier qu'un SMS de commande ou de configuration a bien été envoyé à un appareil, et conserver un journal des messages envoyés.
Changement d'IMEI : lancer des opérations d'alerte ou ouvrir un ticket lorsqu'une carte SIM est détectée dans un appareil inattendu, ou la désactiver via l'API. L'événement inclut le statut de protection contre le vol de la carte SIM, ce qui vous permet de savoir si la modification a été bloquée.
Carte SIM activée ou désactivée : synchronisez votre CRM ou votre base de données d'actifs, prévenez le service d'assistance avant que le client n'appelle, ou lancez la facturation dès l'activation d'une carte SIM. Voir État de la carte SIM.
Seuil d'utilisation dépassé : détecter rapidement un appareil hors de contrôle, ouvrir un incident PagerDuty ou avertir le propriétaire de l'appareil. Voir Limites d'utilisation.
CDR : Intégrez les données d'utilisation des flux dans votre propre système de facturation ou d'analyse, plutôt que de les exporter.
À quoi ressemble un événement ?
Chaque requête présente la même structure externe, à savoir la enveloppe, les détails de l'événement se trouvant à l'intérieur du événement champ. Voici un SMS envoyé par un appareil :
À quoi sert chaque champ de l'enveloppe :
type_d'événementvous indique de quel événement il s'agit, et donc quels champs vous pouvez vous attendre à trouver dansévénement.event_idest propre à cet événement et reste identique à chaque nouvelle tentative. Utilisez-le pour ignorer les doublons.horodatagec'est l'heure à laquelle Simbase a enregistré l'événement, en UTC (RFC 3339).correlation_idétablit un lien entre l'événement et sa cause. Indiquez-le lorsque vous contactez le service d'assistance au sujet d'un événement.id_clientc'est votre compte Simbase.
Seul le événement les modifications varient selon les types. Voici deux autres exemples :
L'IMEI a été modifié
Seuil d'utilisation dépassé (utilisation en octets, le seuil est de null (si ce n'est pas déjà défini)
Les autres types suivent le même schéma. Les événements d'état de la carte SIM contiennent les iccid. Les CDR contiennent l'heure de début et de fin, le type, le volume et le réseau (MCC et MNC). La liste complète des champs pour chaque type figure dans le Référence de l'API.
Définir une destination
Déterminez ce dont vous avez besoin. Quels types d'événements et quels champs de ces événements allez-vous utiliser ? Commencez par le plus simple ; vous pourrez modifier le filtre plus tard.
Obtenir une URL HTTPS qui accepte les requêtes POST : une route sur votre backend, une fonction serverless, ou une URL de webhook Zapier ou Make.com. Elle doit être accessible depuis l'Internet public.
Ajoutez la destination. Dans le tableau de bord, ouvrir Intégrations puis ajoutez une nouvelle destination. Saisissez l'URL, donnez-lui un nom qui vous sera familier, puis définissez le Filtre aux types d'événements de votre choix.
Enregistrez le secret de signature. Le tableau de bord affiche un secret commençant par
whsec_. Il n'apparaît qu'une seule fois, alors conservez-le en lieu sûr, par exemple dans votre gestionnaire de mots de passe ou dans le stockage des secrets de votre application.Répondez rapidement. Votre point de terminaison doit renvoyer un
2xxdéfinir le statut dès réception de la demande, puis effectuer le travail proprement dit par la suite.Vérifier la signature avant de réagir à un événement. Voir Sécurité.
Consultez le registre des livraisons pour les premiers événements, afin de vérifier qu’ils sont bien reçus et que votre point de terminaison répond par
2xx.
Vous pouvez également créer et gérer des destinations via le API, en utilisant une clé API disposant des droits d'accès aux intégrations.
Caractéristiques techniques
Méthode et en-têtes
Chaque transmission s'effectue via HTTPS PUBLICATION avec un corps JSON, envoyée uniquement à des adresses IP publiques. Chaque requête comprend les en-têtes suivants :
identifiant du webhook,horodatage du webhooketsignature du webhook, utilisé pour vérifier la demandeX-Simbase-Intégration-Id, la destination à laquelle la requête a été envoyée
Sécurité
Les demandes sont signées à l'issue de la séance publique Webhooks standard spécification. Simbase signe chaque requête avec l'adresse de destination de whsec_ secret et place le résultat dans le signature du webhook En-tête. Sa vérification permet de s'assurer que la requête provient bien de Simbase et qu'elle n'a pas été altérée.
La solution la plus simple est l'une des applications gratuites Bibliothèques de webhooks standard, disponible pour la plupart des langues : il suffit de transmettre le corps brut de la requête, les en-têtes et votre clé secrète, et la bibliothèque s'occupe du reste, y compris le rejet des anciennes requêtes. Le Référence de l'API propose également un petit exemple permettant de le vérifier sans recourir à une bibliothèque.
Deux points à garder à l'esprit :
Vérifiez le corps brut. Vérifiez que la signature correspond bien au corps du message tel qu'il vous est parvenu, avant que votre framework n'analyse ou ne reformate le JSON.
Ne vous fiez pas aux listes d'adresses IP autorisées. Les serveurs de Simbase sont répartis dans le monde entier et les adresses IP à partir desquelles ils envoient des messages changent au fil du temps. La signature constitue le moyen de vérification fiable.
Si vous transmettez des événements à un outil « no-code » incapable de vérifier les signatures, considérez l'URL elle-même comme une information confidentielle et ne la communiquez à personne.
Si votre serveur utilise un certificat TLS auto-signé, vous pouvez désactiver la vérification du certificat pour cette destination.
Livraison et nouvelles tentatives
Au moins une fois. Un événement peut se produire plusieurs fois. Utilisez
event_idpour ignorer les répétitions.Pas toujours dans l'ordre. Les événements peuvent apparaître dans un ordre différent de celui dans lequel ils se sont produits. Trier par
horodatagelorsque l'ordre a son importance, par exemple pour les changements d'état.Qu'est-ce qui constitue une réussite ? : n'importe quel
2xxcode d'état.Nouvelle tentative avec un délai d'attente pouvant aller jusqu'à 4 heures : délais d'attente,
408,429et5xxréponses. ARetry-AfterL'en-tête est respecté.Non réessayé : tout autre code d'état, redirections comprises.
Suspendu avec effet immédiat : a
410 DisparuCette réponse suspend la destination.Suspendu après 48 heures : Une destination qui échoue sans interruption pendant 48 heures est suspendue. Réactivez-la depuis le tableau de bord ou via l'API pour recommencer à recevoir de nouveaux événements.
Migration depuis les webhooks hérités
Les webhooks hérités continuent de fonctionner, ce qui vous permet d'avancer à votre rythme. Chaque événement hérité a un équivalent direct :
| Webhook hérité | Type d'événement |
|---|---|
SMS reçu ( |
|
Modification de l'IMEI ( |
|
Changement d'état de la carte SIM ( |
|
Limites d'utilisation atteintes ( |
|
SMS reçu (
SMS)Modification de l'IMEI (
IMEI)Changement d'état de la carte SIM (
sim_state)Limites d'utilisation atteintes (
limites_d'utilisation)
Quels sont les changements apportés à la charge utile :
Les détails se déplacent à l'intérieur d'un
événementchamp, contenu dans l'enveloppe décrite ci-dessus.Les horodatages sont au format RFC 3339, en UTC, comme par exemple
2026-11-13T09:30:12Z.Un changement d'état correspond désormais à deux types d'événements, l'un pour l'activation et l'autre pour la désactivation, au lieu de
ancien_Étatetnouvel_étatchamps.La consommation de données est exprimée en octets et non en Mo.
Le nom de l'appareil n'est pas indiqué. Si vous en avez besoin, recherchez-le à l'aide de son ICCID.
Une méthode sûre pour changer :
Ajoutez une destination pour les mêmes types d'événements, en indiquant un nouvel itinéraire sur votre point de terminaison.
Mettez à jour votre code pour lire la nouvelle charge utile et vérifier la signature.
Faites fonctionner les deux en parallèle pendant quelques jours, puis comparez les résultats. Attendez-vous à ce que chaque modification apparaisse deux fois pendant cette période, une fois par système.
Supprimez l'ancien webhook situé sous Intégrations → Webhooks.
Questions fréquentes
Non. Les webhooks hérités continueront de fonctionner dans un avenir proche, mais ne bénéficieront pas de nouvelles fonctionnalités. Les nouvelles intégrations doivent utiliser les événements.
La livraison s'effectue au moins une fois ; il est donc possible qu'une nouvelle tentative arrive après que votre point de terminaison a déjà traité la première. Enregistrez le `event_id` des événements que vous avez gérés et ignorez ceux que vous avez déjà vus.
Soit il a renvoyé `410 Disparu` ou a connu une panne pendant 48 heures d'affilée. Corrigez le point de terminaison, vérifiez le journal de transmission pour identifier l'erreur, puis réactivez la destination sur la page « Intégrations ». Les événements survenus pendant la suspension ne sont pas renvoyés, mais vous pouvez toujours les consulter via l'API pendant 30 jours.
Oui, en les interrogeant via le API. Les requêtes sont décomptées de votre quota API ; il est donc préférable d'opter pour une destination pour tout ce qui est en production.
Oui. Créez une destination pour chaque URL, chacune avec ses propres types d'événements.
Non. Le protocole TLS est imposé afin de garantir la confidentialité des données et la sécurité des communications. Vous pouvez toutefois utiliser un certificat auto-signé et désactiver la vérification du certificat TLS du côté de la destination.
À lire également
Webhooks (ancienne version): l'ancienne méthode de réception des événements, toujours prise en charge
Clés API: créer une clé dotée des champs d'application nécessaires à la gestion des destinations
SMS: les messages associés aux événements SMS, et en quoi ils varient selon les profils
Protection contre le vol: verrouiller une carte SIM sur un IMEI donné, signalé lors des événements de changement d'IMEI
État de la carte SIM: ce que signifient les termes « Activé » et « Désactivé », et ce qui les fait changer
Limites d'utilisation: définir les seuils associés aux événements de seuil
API: gérer les destinations et interroger les événements par programmation



