Catching a runaway device with usage webhooks

A device that suddenly uses far more data than usual is telling you something: a camera whose motion zone now covers a busy road, a router that failed over and stayed there, a firmware update stuck in a loop, or occasionally a device that has been compromised. ThingSIM's webhooks tell your own systems as it happens, so you can act before the SIM reaches its allowance and pauses.

The events that matter for usage

The 80% event is the useful early warning: there is still time to look at the device, or move the SIM to a larger plan, before it pauses. The notification catalogue lists every event and its contents.

Create a webhook

Webhooks can be created in the portal or through the API. Give it an HTTPS URL on a public address and the event types you want:

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

You can send yourself a test event with POST /v1/platform/webhooks/{webhookId}/test to check the endpoint before relying on it.

Receive and verify it

Each event is an HTTPS POST of JSON to your URL. Reply with any 2xx within 10 seconds and do the work afterwards; anything else is retried. Every request carries a Webhook-Signature header with a timestamp t and a signature v1, the HMAC-SHA256 of the timestamp, a full stop and the raw request body, keyed with your signing secret. Verify it against the body exactly as received, before parsing:

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)

The developer overview has the same check in JavaScript and C#, and covers signing-secret rotation.

What to do when the alert arrives

A simple, effective response to an 80% alert:

1. Look at the device. Compare its usage with similar devices; is it doing something new?
2. Fix the cause if it is a fault, such as motion zones, upload settings or a stuck update.
3. Upgrade the SIM if the use is genuine, with POST /v1/iot/sims/{iccid}/plan. An upgrade takes effect straight away.
4. Pause the SIM if the device looks compromised, with POST /v1/iot/sims/{iccid}/pause, then investigate. See securing a device on a public IP.

If you only have a few SIMs, the usage alerts in the portal do the same job without any code; see running a small fleet.

Common questions

When is the usage threshold event sent?

When a SIM passes 80% of its data allowance for the period, and again at 100%.

What happens if my endpoint is down?

Failed deliveries are retried with increasing gaps. If a webhook keeps failing for about a day it is switched off, and your other webhooks receive a platform.webhook.disabled event.

Do I need the API to get usage alerts?

No. Usage alerts can be set in the portal; webhooks are for sending the same events to your own systems.