Een ontsporend apparaat betrappen met verbruikswebhooks

Een apparaat dat ineens veel meer data gebruikt dan normaal, vertelt je iets: een camera waarvan de bewegingszone nu een drukke weg bestrijkt, een router die naar mobiel is overgeschakeld en daar is gebleven, een firmware-update die in een lus zit, of een enkele keer een apparaat dat is gehackt. De webhooks voor dataverbruik van ThingSIM melden het direct aan je eigen systemen, zodat je kunt ingrijpen voordat de simkaart zijn bundel bereikt en pauzeert.

De gebeurtenissen die tellen voor het verbruik

De melding bij 80% is de nuttige vroege waarschuwing: er is nog tijd om naar het apparaat te kijken, of de simkaart naar een grotere bundel te zetten, voordat hij pauzeert. De lijst met notificaties noemt elke gebeurtenis en de inhoud ervan.

Een webhook aanmaken

Je maakt webhooks aan in het portaal of via de API. Geef een HTTPS-URL op een publiek adres op en de soorten gebeurtenissen die je wilt ontvangen:

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"]
  }'

Met POST /v1/platform/webhooks/{webhookId}/test stuur je jezelf een testgebeurtenis, zodat je het endpoint controleert voordat je erop rekent.

Ontvangen en verifiëren

Elke gebeurtenis is een HTTPS-POST met JSON naar je URL. Antwoord binnen 10 seconden met een willekeurige 2xx en doe het werk daarna; al het andere wordt opnieuw geprobeerd. Elk verzoek heeft een header Webhook-Signature met een tijdstempel t en een handtekening v1: de HMAC-SHA256 van de tijdstempel, een punt en de ruwe body van het verzoek, met je signing secret als sleutel. Verifieer hem tegen de body precies zoals ontvangen, voordat je hem verwerkt:

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)

Het ontwikkelaarsoverzicht (in het Engels) heeft dezelfde controle in JavaScript en C#, en beschrijft het vervangen van de signing secret.

Wat je doet als de melding binnenkomt

Een eenvoudige, effectieve reactie op een melding bij 80%:

1. Kijk naar het apparaat. Vergelijk het verbruik met vergelijkbare apparaten; doet het iets nieuws?
2. Los de oorzaak op als het een fout is, zoals bewegingszones, uploadinstellingen of een vastgelopen update.
3. Upgrade de simkaart als het verbruik echt is, met POST /v1/iot/sims/{iccid}/plan. Een upgrade gaat meteen in.
4. Pauzeer de simkaart als het apparaat gehackt lijkt, met POST /v1/iot/sims/{iccid}/pause, en zoek het daarna uit. Zie een apparaat op een publiek IP-adres beveiligen.

Heb je maar een paar simkaarten, dan doen de verbruiksmeldingen in het portaal hetzelfde zonder code; zie een kleine vloot simkaarten beheren.

Veelgestelde vragen

Wanneer wordt de melding voor de verbruiksdrempel verstuurd?

Als een simkaart 80% van zijn databundel voor de periode passeert, en opnieuw bij 100%.

Wat gebeurt er als mijn endpoint niet bereikbaar is?

Mislukte leveringen worden opnieuw geprobeerd, met steeds langere tussenpozen. Blijft een webhook ongeveer een dag mislukken, dan wordt hij uitgezet en ontvangen je andere webhooks een gebeurtenis platform.webhook.disabled.

Heb ik de API nodig voor verbruiksmeldingen?

Nee. Verbruiksmeldingen stel je in het portaal in; webhooks zijn er om dezelfde gebeurtenissen naar je eigen systemen te sturen.