# Notification types

> Every event the API can send to a webhook, grouped by service area, with the `data` each one carries.

## The event envelope

Every webhook POST carries one event. Its `data` depends on `type`. Verify the `Webhook-Signature` header first: https://thingsim.com/developers#verifying-signatures

- `id` (string, required): `evt_…`. Unique per event; deliveries can repeat, so de-duplicate on it. Example: `evt_0192a4c3e5f67b8d9e0f1a2b3c4d5e72`.
- `type` (string, required): The notification type. Example: `iot.sim.allowance_reached`.
- `serviceArea` (ServiceArea, required): The product area a notification belongs to; `platform` is the account itself. One of `voice`, `connectivity`, `hosting`, `iot`, `platform`. Example: `iot`.
- `organisationId` (string (uuid), required): The organisation the event is about. Example: `0f8b6c1e-5a2d-4c7e-9b3a-2d1e6f4a7c90`.
- `occurredAt` (string (date-time), required): When the change took effect. Example: `2026-09-25T09:12:44Z`.
- `data` (object, required): The type's payload; see the notification catalogue. Example: `{"iccid":"8944110068212345678","label":"Car park barrier 3","planId":"5b0e4f2a-8c1d-4e6f-9a3b-7d2c1e0f4a61","allowanceBytes":1073741824,"usedBytes":1073741824,"periodEnd":"2026-10-01T00:00:00Z"}`.

## IoT SIMs

### iot.sim.activated

A SIM's activation took effect on the network. Billing for the SIM starts now.

```json
{
  "iccid": "8944110068212345678",
  "label": "Car park barrier 3",
  "status": "active",
  "planId": "5b0e4f2a-8c1d-4e6f-9a3b-7d2c1e0f4a61",
  "activatedAt": "2026-09-25T09:31:02Z"
}
```

### iot.sim.paused

A SIM stopped passing data, sent once the network has applied it. `reason` says why: `customerPause` (you paused it), `nonPayment` (a payment failed) or `provider` (our operations team). A SIM stopped for using its allowance sends `iot.sim.allowance_reached` instead.

```json
{
  "iccid": "8944110068212345678",
  "label": "Car park barrier 3",
  "status": "paused",
  "reason": "customerPause"
}
```

### iot.sim.resumed

A paused or suspended SIM is passing data again, sent once the network has applied it. `previousReason` says why it had stopped: `customerPause`, `nonPayment` or `provider`.

```json
{
  "iccid": "8944110068212345678",
  "label": "Car park barrier 3",
  "status": "active",
  "previousReason": "customerPause"
}
```

### iot.sim.ceased

A SIM was permanently ceased and has stopped passing data. Sent when the cease takes effect on the network, which for a cease dated in the future is that date.

```json
{
  "iccid": "8944110068212345678",
  "label": "Car park barrier 3",
  "status": "ceased",
  "ceasedAt": "2026-09-25T10:02:17Z",
  "billedUntil": "2026-10-01T00:00:00Z"
}
```

### iot.sim.plan_changed

A SIM moved to a new plan. Sent when the change takes effect: straight away for an upgrade, at renewal for a downgrade.

```json
{
  "iccid": "8944110068212345678",
  "label": "Car park barrier 3",
  "fromPlanId": "5b0e4f2a-8c1d-4e6f-9a3b-7d2c1e0f4a61",
  "toPlanId": "9c7a2e14-3b5d-4f60-8e21-6a4b0d9c3f75",
  "direction": "upgrade",
  "effectiveAt": "2026-09-25T00:00:00Z"
}
```

### iot.sim.usage_threshold

A SIM passed a threshold of its data allowance for the period: 80%, and 100% for a SIM that carries on at overage rates rather than pausing. Each threshold is sent once per period. SIMs in a shared data pool are not sent this individually.

```json
{
  "iccid": "8944110068212345678",
  "label": "Car park barrier 3",
  "thresholdPercent": 80,
  "allowanceBytes": 1073741824,
  "usedBytes": 859832320,
  "periodEnd": "2026-10-01T00:00:00Z"
}
```

### iot.sim.allowance_reached

A SIM used its whole data allowance for the period and has paused. It resumes when the allowance resets, or straight away if you upgrade its plan.

```json
{
  "iccid": "8944110068212345678",
  "label": "Car park barrier 3",
  "planId": "5b0e4f2a-8c1d-4e6f-9a3b-7d2c1e0f4a61",
  "allowanceBytes": 1073741824,
  "usedBytes": 1073741824,
  "periodEnd": "2026-10-01T00:00:00Z"
}
```

## Platform

### platform.webhook.disabled

A webhook was switched off after failing for about 24 hours. Sent to your other webhooks. Fix the endpoint, then re-enable it.

```json
{
  "webhookId": "wh_4f1c2b7e9a0d4e6f8b3c5d7e9f1a2b3c",
  "url": "https://example.com/hooks/thingsim",
  "failingSince": "2026-09-24T09:12:45Z",
  "lastResponseStatus": 503
}
```

### platform.webhook.test

A test event, sent only to the webhook it was requested for, whatever types it has chosen.

```json
{
  "webhookId": "wh_4f1c2b7e9a0d4e6f8b3c5d7e9f1a2b3c",
  "message": "This is a test event. Answer with any 2xx status within 10 seconds."
}
```

Source: https://thingsim.com/developers/notifications