Un webhook est un message que votre application reçoit dès qu'un événement se produit, ce qui vous évite d'avoir à demander sans cesse « Y a-t-il du nouveau ? ». Lorsqu'un événement se produit au sein de votre compte Simbase, Simbase transmet cet événement en temps réel à une URL que vous contrôlez.

Voici comment intégrer Simbase au reste de votre infrastructure. Un SMS arrive sur une carte SIM et votre canal Slack envoie une notification. Un appareil change d'IMEI et votre système de tickets ouvre un incident. Le volume de données mensuel dépasse un seuil et votre tableau de bord d'utilisation se met à jour. Tout cela sans avoir à écrire de code pour interroger notre API.

Les webhooks couvrent les événements qui se produisent du côté de Simbase : SMS entrants, modifications de l'IMEI, changements d'état de la carte SIM, limitation du débit et seuils d'utilisation.

Prêt à mettre en ligne ? Enregistrez votre point de terminaison de webhook sur le tableau de bord afin que Simbase sache où transmettre les événements.

Comment Simbase utilise les webhooks

Lorsqu'un événement se produit sur votre compte, Simbase envoie une requête POST via HTTPS à l'URL que vous avez indiquée, avec un corps JSON décrivant l'événement. Votre application lit ce corps, effectue les opérations que vous souhaitez, puis renvoie un code d'état 2xx pour confirmer la réception du message.

Il n'est pas nécessaire de mettre en place une solution sophistiquée du côté du destinataire. L'« URL que vous indiquez » peut être l'une des suivantes :

• Une plateforme d'automatisation sans code, comme Zapier ou Make.com

• Un outil de discussion d'équipe tel que Slack ou Microsoft Teams, utilisant leurs URL de webhooks entrants intégrées (directement ou via Zapier ou Make.com)

• Une fonction sur votre propre backend, dans n'importe quel langage

• Un fournisseur de SMS tiers, tel que Twilio ou MessageBird, si vous souhaitez envoyer des SMS vers des numéros de téléphone publics

• Une fonction sans serveur sur AWS Lambda, Vercel, Cloudflare Workers, Google Cloud Functions, etc.

Si vous pouvez nous fournir une URL HTTPS, nous pourrons y diffuser des événements.

Événements Webhook

Simbase prend en charge les types d'événements suivants :

• SMS reçus

• Modifications de l'IMEI

• Changement d'état de la carte SIM

• Limitation du débit

• L'utilisation dépasse le seuil

SMS reçus

Les cartes SIM Simbase fonctionnent au sein de ce que nous appelons un « circuit SMS fermé ». En termes simples : votre carte SIM peut envoyer des SMS à notre serveur via le numéro court +55555 et recevoir des SMS de notre serveur, mais elle ne peut échanger de SMS avec aucun autre numéro de téléphone dans le monde. C'est voulu. Il s’agit d’une mesure de sécurité qui rend votre flotte inaccessible depuis le réseau SMS public : ainsi, personne ne peut envoyer de SMS à vos appareils, aucune arnaque par SMS surtaxé ne peut vider votre crédit, et les SMS ne peuvent pas être utilisés comme vecteur d’attaque contre votre matériel.

Vous pouvez bien sûr toujours envoyer et recevoir des SMS depuis vos appareils. Les messages transitent simplement par Simbase plutôt que par le réseau mobile public. Et c'est précisément là que ce webhook prend toute sa puissance.

Lorsque votre appareil envoie un SMS au +55555, deux choses se produisent :

1. Le message s'affiche sur le tableau de bord Simbase.

2. Si vous avez enregistré un webhook SMS, Simbase transfère le message complet via HTTPS vers votre point de terminaison.

C'est cette deuxième étape que la plupart des clients sous-estiment. La charge utile contient le corps du message, l'ICCID de la carte SIM, le nom de l'appareil et un horodatage. Une fois que ces informations parviennent à votre terminal, vous pouvez en faire ce que vous voulez.

Voici quelques exemples concrets de ce que les utilisateurs réalisent grâce à ce webhook :

• Transférez le contenu du SMS vers un canal Slack ou Microsoft Teams afin que l'équipe puisse consulter en temps réel les messages provenant des appareils. Cette fonctionnalité est utile pour les dispositifs de suivi d'actifs, les distributeurs automatiques, les capteurs à distance ou tout autre appareil qui transmet des informations par SMS.

• Transférez les données vers Zapier ou Make.com et déclenchez toutes les actions prises en charge par ces plateformes : enregistrer des données dans Google Sheets, envoyer un e-mail, mettre à jour un CRM, créer un ticket Zendesk ou Intercom, publier un contenu sur Notion, etc. Aucune connaissance en programmation n'est requise.

• Transmettez le SMS vers un numéro de téléphone externe via Twilio, MessageBird ou tout autre fournisseur de SMS. Votre appareil envoie un SMS via Simbase, votre webhook le reçoit, votre code transfère le corps du message à Twilio, et Twilio le transmet à un téléphone mobile classique. C'est ainsi que les clients établissent une liaison unidirectionnelle entre un parc d'appareils IoT verrouillé et un numéro de téléphone classique, sans renoncer à la sécurité du circuit fermé.

• Analysez le corps du SMS pour extraire les mesures des capteurs ou les commandes, puis enregistrez-les dans votre propre base de données ou dans un système de stockage de séries chronologiques tel qu’InfluxDB ou TimescaleDB.

• Déclencher une action au niveau de la carte SIM. Votre terminal reçoit le SMS, détermine que « cet appareil présente un comportement anormal », puis appelle l'API Simbase pour désactiver la carte SIM, limiter son débit ou l'assigner à une autre politique.

Pour les lecteurs qui ne programment pas, voici l'essentiel en quelques mots : le webhook SMS est ce qui transforme « un SMS reçu sur une carte SIM » en « une notification envoyée sur Slack », « la mise à jour d'une feuille de calcul », « l'envoi d'un e-mail à l'équipe » ou « l'ouverture d'un ticket ». Vous n'avez pas besoin de comprendre le fonctionnement du routage des SMS. Il vous suffit de configurer Simbase pour qu'il pointe vers la bonne URL. En savoir plus sur les SMS ici.

Corps du webhook JSON

{
  "event": "sms",
  "iccid": "8912300000001234567",
  "timestamp": "2022-12-23 12:31:09",
  "message": "test SMS message",
  "deviceName": "Demo device"
}

Modification de l'IMEI

Chaque appareil dispose d'un numéro IMEI (International Mobile Equipment Identity), un identifiant unique à 15 chiffres intégré au matériel. Lorsque votre carte SIM est insérée dans un autre appareil, l'opérateur mobile détecte le nouvel IMEI et le signale. Simbase peut avertir votre terminal dès que cela se produit.

L'importance de cette question dépend de votre activité. Qu'il s'agisse de suivi des actifs, de logistique ou de gestion de flotte, un changement inattendu d'IMEI est l'un des signes les plus évidents indiquant qu'une carte SIM a été retirée de l'appareil auquel elle était destinée, que ce soit à la suite d'un vol, d'une manipulation frauduleuse ou d'une intervention de maintenance qui a mal tourné. Pour les fabricants d'équipements d'origine (OEM) qui expédient des appareils préconfigurés, les événements de modification d'IMEI permettent de vérifier que chaque carte SIM s'est bien retrouvée dans l'appareil auquel elle était destinée.

Voici comment ce webhook est généralement utilisé :

• Signalez l'incident sur Slack ou par e-mail afin que votre équipe opérationnelle puisse se pencher sur la question.

• Créer automatiquement un ticket dans votre outil d'assistance lorsque le nouvel IMEI ne correspond pas à l'appareil attendu.

• Désactivez la carte SIM via l'API Simbase si votre politique de sécurité considère les changements inattendus d'IMEI comme un signe de fraude.

• Enregistrez cette modification dans votre base de données d'actifs afin de toujours savoir quelle carte SIM se trouve dans quel appareil, sans avoir à effectuer de rapprochement manuel.

• Envoyez l'événement vers un système SIEM ou un journal d'audit à des fins de conformité et d'analyse forensic.

Corps du webhook JSON

{
  "event": "imei",
  "timestamp": "2022-12-23 12:34:07",
  "iccid": "8912300000001234567",
  "oldIMEI": "None",
  "newIMEI": "355234090012345",
  "action": "disabled",
  "deviceName": "Demo device"
}

Changements d'état de la carte SIM

Une carte SIM possède un état qui indique si elle est actuellement activée, désactivée, suspendue, etc. Cet état peut changer pour plusieurs raisons :

• Activation ou désactivation manuelle via le tableau de bord ou l'API

• Activation automatique lors de la première utilisation de la carte SIM

• Solde épuisé

• Incidents tels que des vols ou des soupçons de fraude

• Modifications de l'IMEI déclenchant une règle

Lorsque l'état change, Simbase transmet le nouvel état à votre webhook afin que le reste de votre infrastructure puisse réagir en conséquence. En savoir plus sur les états SIM ici.

Ce que les clients ont tendance à faire lors de cet événement :

• Assurez la synchronisation d'un CRM, d'un ERP ou d'une base de données d'actifs interne avec l'état réel de chaque carte SIM, sans avoir à interroger l'API Simbase.

• Recevez une alerte sur Slack ou par e-mail dès qu'une carte SIM est désactivée, afin que le service d'assistance en soit informé avant même que le client n'appelle.

• Lancez l'automatisation de la facturation dès la première activation d'une carte SIM, en transmettant l'événement à Stripe, Chargebee ou à un service de facturation personnalisé via Zapier ou votre propre backend.

• Détectez les imprévus dès leur apparition. Si une carte SIM a été désactivée et que personne de votre équipe ne s'y attendait, considérez automatiquement cela comme un incident.

Corps du webhook JSON

{
  "event": "sim_state",
  "timestamp": "2022-12-23 12:42:57",
  "iccid": "8912300000001234567",
  "old_state": "enabled",
  "new_state": "disabled",
  "deviceName": "Demo device"
}

Limitation de débit

Vous pouvez définir des règles de trafic dans le tableau de bord Simbase afin de limiter automatiquement le débit de données d'une carte SIM dès que sa consommation mensuelle dépasse le seuil que vous avez choisi. Lorsqu'une carte SIM est soumise à une limitation de débit, Simbase peut déclencher un webhook afin que vous ne l'appreniez pas par un client mécontent.

Voici quelques actions utiles à effectuer une fois que l'événement est parvenu à votre point de terminaison :

• Envoyez un e-mail ou un SMS au propriétaire de l'appareil avec un message clair : « Votre appareil est limité à 100 Ko/s jusqu'à la fin du mois ».

• Insérez une fiche dans votre outil d'assistance afin que l'équipe soit prête dès qu'une plainte concernant une « connexion lente » est signalée.

• Mettez à jour le tableau de bord destiné aux clients afin que ceux-ci puissent voir exactement à quel moment la limitation a été activée.

• Déclencher un processus de vente incitative ou de passage à un forfait supérieur si un client atteint régulièrement le plafond.

• Envoyez l'événement sur Slack afin que l'équipe d'ingénierie puisse observer en temps réel les tendances en matière de limitation de débit sur l'ensemble du parc.

Corps du webhook JSON

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

L'utilisation dépasse le seuil

Même sans définir de politique de trafic, vous pouvez déclencher un webhook lorsque la consommation mensuelle de données d'une carte SIM dépasse un seuil défini.

C'est un moyen efficace de détecter rapidement un appareil qui présente un dysfonctionnement. Une carte SIM qui consomme habituellement 10 Mo par mois et qui dépasse soudainement les 100 Mo cherche généralement à vous signaler quelque chose : un bug du firmware, un basculement vers le Wi-Fi qui a mal tourné, un appareil resté en mode débogage, une mise à jour OTA qui a dérapé ou, dans le pire des cas, une carte SIM volée utilisée pour le partage de connexion.

Ce que les clients ont tendance à faire lors de cet événement :

• Envoyer une alerte sur Slack ou par e-mail lorsqu'une carte SIM dépasse la limite définie,

• Créez un incident dans PagerDuty ou Opsgenie pour les déploiements hautement prioritaires.

• Limiter ou désactiver automatiquement la carte SIM via l'API Simbase.

• Lancez un flux Zapier ou Make.com qui envoie une notification au propriétaire de l'appareil avant que la facture ne grimpe.

• Enregistrez cet événement dans un tableau de bord dédié aux anomalies d'utilisation afin de pouvoir identifier les tendances à l'échelle de la flotte au fil du temps.

Corps du webhook JSON lorsque l'utilisation dépasse 100 Mo

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

Étapes à suivre pour recevoir des webhooks

En quelques étapes seulement, vous pouvez commencer à recevoir des notifications d'événements dans votre application :

1. Déterminez les événements que vous souhaitez surveiller et les champs de la charge utile qui vous intéressent réellement.

2. Créez un point de terminaison HTTP(S) pour recevoir les événements. Il peut s'agir d'une route sur votre backend, d'une fonction sans serveur, d'une URL de webhook Zapier, d'une URL de webhook Make.com, d'un webhook entrant Slack (avec une petite transformation en amont) ou de toute autre URL acceptant les requêtes POST.

3. Analysez le corps JSON de votre côté et renvoyez un code d'état 2xx. Seul le code d'état importe pour Simbase, et non le corps de la réponse.

4. Testez le point de terminaison à l'aide d'un outil tel que Facteur ou curl. Si vous souhaitez recevoir des événements Simbase en temps réel pendant que vous développez sur votre ordinateur portable, un outil de tunneling tel que ngrok ou Cloudflare Tunnel fonctionne très bien.

5. Déployez votre point de terminaison derrière une URL HTTPS accessible au public.

6. Enregistrez cette URL dans le Tableau de bord Simbase dans la rubrique « Intégrations ».

7. Simbase envoie un événement de test à votre URL. Si votre point de terminaison renvoie un code 2xx, le webhook est enregistré et commence à recevoir des événements en temps réel.

Caractéristiques techniques

Méthode

Tous les appels émis par Simbase vers votre webhook sont des requêtes HTTP POST comportant un corps au format JSON.

Sécurité

• Chaque appel comporte un en-tête nommé x-simbase-requesttoken. Pour les appels de test, la valeur est test-test-test-test-test. Utilisez cet en-tête de votre côté pour vérifier que la requête provient bien de Simbase avant d'y donner suite.

• N'utilisez pas le filtrage par adresse IP comme mesure de sécurité. Nos serveurs sont répartis dans le monde entier et les adresses IP publiques à partir desquelles ils envoient des messages changent au fil du temps ; une liste blanche d'adresses IP deviendrait donc inopérante au pire moment possible.