Webhooks : repérer un équipement qui consomme trop

Un équipement qui consomme soudain beaucoup plus de données que d’habitude vous dit quelque chose : une caméra dont la zone de détection couvre désormais une route passante, un routeur qui a basculé sur le secours 4G et y est resté, une mise à jour de firmware bloquée en boucle, ou parfois un équipement compromis. Les webhooks ThingSIM préviennent vos propres systèmes en temps réel, pour que vous puissiez agir avant que la carte SIM atteigne son forfait et se mette en pause.

Les événements utiles pour la consommation

L’événement à 80 % est l’alerte précoce utile : il reste du temps pour examiner l’équipement, ou passer la carte SIM à un forfait supérieur, avant la mise en pause. Le catalogue des notifications liste tous les événements et leur contenu.

Créer un webhook

Les webhooks se créent dans le portail ou par l’API. Indiquez une URL HTTPS sur une adresse publique et les types d’événements souhaités :

curl -X POST "https://partners.netavo.com/api/v1/platform/webhooks" \
  -H "Authorization: Bearer $THINGSIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/thingsim/events",
    "description": "Usage alerts",
    "types": ["iot.sim.usage_threshold", "iot.sim.allowance_reached"]
  }'

Vous pouvez vous envoyer un événement de test avec POST /v1/platform/webhooks/{webhookId}/test pour vérifier le point de terminaison avant de compter dessus.

Le recevoir et le vérifier

Chaque événement est un POST HTTPS de JSON vers votre URL. Répondez par n’importe quel code 2xx en moins de 10 secondes et faites le traitement ensuite ; toute autre réponse entraîne une nouvelle tentative. Chaque requête porte un en-tête Webhook-Signature avec un horodatage t et une signature v1 : le HMAC-SHA256 de l’horodatage, d’un point et du corps brut de la requête, calculé avec votre secret de signature. Vérifiez-le sur le corps exactement tel que reçu, avant de l’analyser :

import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.strip().split("=", 1) for p in header.split(",") if "=" in p)
    t, sig = parts.get("t"), parts.get("v1")
    if not t or not sig or abs(time.time() - int(t)) > tolerance:
        return False
    signed = t.encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig)

La présentation pour les développeurs donne la même vérification en JavaScript et en C#, et explique la rotation du secret de signature.

Que faire quand l’alerte arrive

Une réponse simple et efficace à une alerte à 80 % :

1. Examinez l’équipement. Comparez sa consommation à celle d’équipements similaires : fait-il quelque chose de nouveau ?
2. Corrigez la cause s’il s’agit d’un défaut : zones de détection, réglages d’envoi, mise à jour bloquée.
3. Passez la carte SIM au forfait supérieur si l’usage est légitime, avec POST /v1/iot/sims/{iccid}/plan. Le passage au forfait supérieur s’applique immédiatement.
4. Mettez la carte SIM en pause si l’équipement semble compromis, avec POST /v1/iot/sims/{iccid}/pause, puis enquêtez. Voir sécuriser un équipement sur une IP publique.

Si vous n’avez que quelques cartes SIM, les alertes de consommation du portail font le même travail sans code ; voir gérer un petit parc de cartes SIM.

Questions fréquentes

Quand l’événement de seuil de consommation est-il envoyé ?

Quand une carte SIM dépasse 80 % de son forfait de données pour la période, puis de nouveau à 100 %.

Que se passe-t-il si mon point de terminaison est indisponible ?

Les envois échoués sont retentés à intervalles croissants. Si un webhook échoue pendant environ une journée, il est désactivé, et vos autres webhooks reçoivent un événement platform.webhook.disabled.

Faut-il l’API pour recevoir des alertes de consommation ?

Non. Les alertes de consommation se règlent dans le portail ; les webhooks servent à envoyer les mêmes événements à vos propres systèmes.