Configurer les webhooks dans Simbase

Un webhook est un message que votre application reçoit dès qu'un événement se produit, au lieu de devoir demander en boucle « du nouveau ? » Quand un événement se produit dans votre compte Simbase, Simbase envoie cet événement en temps réel vers une URL que vous contrôlez.

C'est ainsi que vous connectez Simbase au reste de votre stack. Un SMS arrive sur une SIM et votre canal Slack reçoit une notification. Un appareil change d'IMEI et votre outil de ticketing ouvre un incident. La consommation de données du mois dépasse un seuil et votre tableau de bord se met à jour. Le tout sans écrire de code qui interroge notre API en boucle.

Les webhooks couvrent les événements qui se produisent côté Simbase : SMS entrants, changements d'IMEI, changements de statut des SIM et limites d'utilisation atteintes.

Prêt à passer en production ? Enregistrez votre endpoint de webhook dans le tableau de bord pour indiquer à Simbase où envoyer les événements.

Comment Simbase utilise les webhooks

Quand un événement se produit sur votre compte, Simbase envoie une requête HTTPS POST à l'URL que vous indiquez, avec un body JSON qui décrit l'événement. Votre application lit le body, en fait ce que vous voulez et répond avec un code de statut 2xx pour confirmer la réception du message.

Pas besoin de construire quelque chose de complexe côté réception. L'« URL que vous indiquez » peut être :

• Une plateforme d'automatisation no-code comme Zapier ou Make.com

• Un outil de messagerie d'équipe comme Slack ou Microsoft Teams, via leurs URL de webhook entrant intégrées (directement ou avec Zapier ou Make.com entre les deux)

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

• Un fournisseur SMS tiers comme Twilio ou MessageBird, si vous voulez relayer les SMS vers des numéros de téléphone publics

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

Si vous pouvez nous donner une URL HTTPS, nous pouvons y envoyer des événements.

Événements de webhook

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

• SMS reçus

• Changement d'IMEI

• Changements de statut de la SIM

• Limites d'utilisation atteintes

SMS reçus

Les SIM des profils Black, Red et Green fonctionnent dans ce que nous appelons un circuit SMS fermé. Concrètement : la SIM peut envoyer des SMS à notre serveur au numéro court +55555 et recevoir des SMS de notre serveur, mais elle ne peut échanger de SMS avec aucun autre numéro. C'est voulu. Cette mesure de sécurité rend votre flotte injoignable depuis le réseau SMS public : personne ne peut envoyer de SMS à vos appareils, aucune arnaque aux numéros surtaxés ne peut vider votre solde et le SMS ne peut pas servir de vecteur d'attaque contre votre matériel.

Les SIM des profils Blue, Yellow et Cyan sont livrées avec un MSISDN, donc des numéros externes peuvent leur envoyer des SMS. Les messages envoyés par ces appareils restent malgré tout dans Simbase et ne sont jamais remis à un téléphone externe : le webhook se comporte donc de la même façon sur tous les profils. Consultez SMS pour le détail par profil.

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

1. Le message apparaît dans le tableau de bord Simbase.

2. Si vous avez enregistré un webhook SMS, Simbase transmet le message complet en HTTPS à votre endpoint.

C'est cette deuxième étape que la plupart des clients sous-estiment. Le payload contient le texte du message, l'ICCID de la SIM, le nom de l'appareil et un horodatage. Une fois qu'il arrive sur votre endpoint, vous pouvez en faire ce que vous voulez.

Quelques exemples concrets de ce que les clients construisent avec ce webhook :

• Transférer le texte du SMS vers un canal Slack ou Microsoft Teams pour que l'équipe voie les messages des appareils en direct. Pratique pour les traceurs, les distributeurs automatiques, les capteurs distants ou tout appareil qui communique par SMS.

• Envoyer le payload vers Zapier ou Make.com et déclencher tout ce que ces plateformes permettent : enregistrer dans Google Sheets, envoyer un e-mail, mettre à jour un CRM, créer un ticket Zendesk ou Intercom, publier dans Notion, etc. Sans code.

• Relayer le SMS vers un numéro externe via Twilio, MessageBird ou un autre fournisseur SMS. Votre appareil envoie un SMS via Simbase, votre webhook le reçoit, votre code transmet le texte à Twilio et Twilio le remet sur un téléphone mobile classique. C'est ainsi que des clients créent une passerelle à sens unique entre une flotte IoT verrouillée et un numéro de téléphone normal, sans renoncer à la sécurité du circuit fermé.

• Extraire du texte du SMS des mesures de capteurs ou des commandes et les stocker dans votre propre base de données ou dans une base de séries temporelles comme InfluxDB ou TimescaleDB.

• Déclencher une action sur la SIM. Votre endpoint reçoit le SMS, décide que « cet appareil se comporte mal » et appelle l'API Simbase pour désactiver la SIM.

Pour ceux qui ne codent pas, en bref : le webhook SMS transforme « un SMS est arrivé sur une SIM » en « Slack a reçu une notification », « le tableur est à jour », « l'équipe a reçu un e-mail » ou « un ticket a été ouvert ». Inutile de comprendre le routage des SMS. Il suffit d'indiquer à Simbase la bonne URL. Consultez SMS.

Body JSON du webhook

{
  "event": "sms",
  "iccid": "8900000000001234567",
  "timestamp": "2026-08-06 12:00:00",
  "message": "test SMS message",
  "deviceName": "Demo device"
}

Changement d'IMEI

Chaque appareil possède un IMEI (International Mobile Equipment Identity), un identifiant unique à 15 chiffres intégré au matériel. Quand votre SIM est placée dans un autre appareil, le réseau mobile détecte le nouvel IMEI et le signale. Simbase peut en informer votre endpoint immédiatement.

L'intérêt dépend de votre activité. Pour le suivi d'actifs, la logistique ou la gestion de flotte, un changement d'IMEI inattendu est l'un des signes les plus forts qu'une SIM a été retirée de son appareil prévu, que ce soit par vol, manipulation ou maintenance qui tourne mal. Pour les OEM qui livrent des appareils préprovisionnés, les changements d'IMEI permettent de confirmer que chaque SIM est bien arrivée dans le bon appareil.

Ce que les clients font généralement avec ce webhook :

• Publier l'événement dans Slack ou par e-mail pour que votre équipe opérationnelle l'examine.

• Ouvrir automatiquement un ticket dans votre outil de support quand le nouvel IMEI ne correspond à aucun appareil attendu.

• Désactiver la SIM via l'API Simbase si votre politique de sécurité considère un changement d'IMEI inattendu comme un signal de fraude.

• Enregistrer le changement dans votre base d'actifs pour toujours savoir quelle SIM se trouve dans quel appareil, sans rapprochement manuel.

• Envoyer l'événement vers un SIEM ou un journal d'audit pour la conformité et l'analyse forensique.

Body JSON du webhook

{
  "event": "imei",
  "timestamp": "2026-08-06 12:00:00",
  "iccid": "8900000000001234567",
  "oldIMEI": "None",
  "newIMEI": "355234090012345",
  "action": "disabled",
  "deviceName": "Demo device"
}

Changements de statut de la SIM

Une SIM a un statut qui indique si elle est activée ou désactivée. Ce statut peut changer pour plusieurs raisons :

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

• Activation automatique à la première utilisation de la SIM

• Solde épuisé

• Incidents comme un vol ou une fraude présumée

• Changements d'IMEI non autorisés

Quand le statut change, Simbase envoie le nouveau statut à votre webhook pour que le reste de votre stack puisse réagir. Consultez Statut de la SIM.

Ce que les clients font généralement avec cet événement :

• Garder un CRM, un ERP ou une base d'actifs interne synchronisé avec le statut réel de chaque SIM, sans interroger l'API Simbase en boucle.

• Recevoir une alerte Slack ou un e-mail dès qu'une SIM est désactivée, pour que le support soit au courant avant l'appel du client.

• Lancer l'automatisation de la facturation quand une SIM est activée pour la première fois, en envoyant l'événement vers Stripe, Chargebee ou un service de facturation maison via Zapier ou votre propre backend.

• Repérer les surprises tôt. Si une SIM a été désactivée sans que personne dans votre équipe ne s'y attende, traitez-le automatiquement comme un incident.

Body JSON du webhook

{
  "event": "sim_state",
  "timestamp": "2026-08-06 12:00:00",
  "iccid": "8900000000001234567",
  "old_state": "enabled",
  "new_state": "disabled",
  "deviceName": "Demo device"
}

Limites d'utilisation atteintes

Vous pouvez définir un plafond mensuel de données ou de SMS sur n'importe quelle SIM. Quand la consommation dépasse ce plafond, Simbase désactive automatiquement la SIM, et ce webhook en informe immédiatement le reste de votre stack.

Les plafonds sont vérifiés à l'arrivée des relevés de consommation de l'opérateur, pas en temps réel. Une SIM peut donc dépasser légèrement son plafond avant d'être désactivée. Consultez Limites d'utilisation pour comprendre ce dépassement et savoir comment le prévoir dans votre budget.

C'est un bon moyen de repérer tôt un appareil qui dysfonctionne. Une SIM qui consomme normalement 10 Mo par mois et atteint soudain son plafond cherche souvent à vous dire quelque chose : un bug de firmware, un repli Wi-Fi qui a mal tourné, un appareil resté en mode debug, une mise à jour OTA qui s'emballe ou, dans le pire des cas, une SIM volée utilisée pour du partage de connexion.

Ce que les clients font généralement avec cet événement :

• Envoyer une alerte dans Slack ou par e-mail, pour que l'équipe sache qu'une SIM est hors ligne avant l'appel du client

• Ouvrir un incident dans PagerDuty ou Opsgenie pour les déploiements prioritaires

• Vérifier l'appareil, puis réactiver la SIM ou relever sa limite via l'API Simbase

• Déclencher un scénario Zapier ou Make.com qui prévient le propriétaire de l'appareil

• Enregistrer l'événement dans un tableau de bord des anomalies de consommation pour repérer les tendances sur toute la flotte

Body JSON du webhook

{
  "event": "usage_limits",
  "timestamp": "2026-08-06 12:00:00",
  "iccid": "8900000000001234567",
  "usage_mb": 102,
  "threshold_mb": 100,
  "usage_sms": 0,
  "threshold_sms": null
}

Étapes pour recevoir des webhooks

Quelques étapes suffisent pour recevoir des notifications d'événements dans votre application :

1. Choisissez les événements à écouter et les champs du payload qui vous intéressent vraiment.

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

3. Analysez le body JSON de votre côté et renvoyez un code de statut 2xx. Seul le code de statut compte pour Simbase, pas le body de la réponse.

4. Testez l'endpoint avec un outil comme Postman ou curl. Pour recevoir de vrais événements Simbase pendant que vous développez sur votre ordinateur, un outil de tunnel comme ngrok ou Cloudflare Tunnel fonctionne bien.

5. Déployez votre endpoint derrière une URL HTTPS accessible publiquement.

6. Enregistrez cette URL dans le tableau de bord Simbase sous Integrations → Webhooks.

7. Simbase envoie un événement de test à votre URL. Si votre endpoint répond avec un code 2xx, le webhook est enregistré et commence à recevoir les événements réels.

Spécifications

Méthode

Tous les appels de Simbase vers votre webhook sont des requêtes HTTP POST avec un body JSON.

Sécurité

• N'utilisez pas le filtrage IP comme mesure de sécurité. Nos serveurs sont répartis dans le monde entier et les IP publiques depuis lesquelles ils envoient changent avec le temps : une liste d'IP autorisées finira par casser au pire moment.

Questions fréquentes

Articles associés

• SMS : les messages que transmet le webhook des SMS reçus, et leurs différences selon le profil

• Protection contre le vol : verrouiller une SIM sur un IMEI pour qu'un changement soit bloqué, pas seulement signalé

• Statut de la SIM : ce que signifient Activée et Désactivée et ce qui modifie le statut

• Limites d'utilisation : définir le plafond qui déclenche le webhook de consommation

• Clés API : créer une clé et la limiter à ce dont l'intégration a besoin

• API : lister, créer et supprimer des webhooks par programmation