# Catching a runaway device with usage webhooks

> Using ThingSIM's usage webhooks to hear when a SIM passes 80% of its allowance, so a misbehaving device is caught before it pauses.

Fleets & developers · 2 July 2026

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

| Event | When it is sent |
|---|---|
| `iot.sim.usage_threshold` | A SIM passes 80% of its allowance for the period, and 100% |
| `iot.sim.allowance_reached` | A SIM used its whole allowance and has paused |
| `iot.sim.allowance_reset` | A new period started; SIMs paused at their allowance resume |
| `iot.sim.plan_changed` | A SIM moved to a new plan |

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](/developers/notifications) 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:

```bash
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:

```python
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](/developers) 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](/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](/running-a-small-sim-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.

## Recommended plan

1 GB, UK 4-network: £2.40 a month per active SIM, ex VAT.

Source: https://thingsim.com/usage-webhooks