Developers

Notification types

Every event we can send to your webhook, grouped by service area. Subscribe to types by name, or to a whole service area.

The event envelope

Every webhook POST carries one event as JSON. The envelope is the same for every type; data is the type's payload, shown for each type below. Check the Webhook-Signature header before trusting it: how to verify a signature.

  • 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

  • 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"}

Example event
{
  "id": "evt_0192a4c3e5f67b8d9e0f1a2b3c4d5e72",
  "type": "iot.sim.activated",
  "serviceArea": "iot",
  "organisationId": "0f8b6c1e-5a2d-4c7e-9b3a-2d1e6f4a7c90",
  "occurredAt": "2026-09-25T09:12:44Z",
  "data": {
    "iccid": "8944110068212345678",
    "label": "Car park barrier 3",
    "status": "active",
    "planId": "5b0e4f2a-8c1d-4e6f-9a3b-7d2c1e0f4a61",
    "activatedAt": "2026-09-25T09:31:02Z"
  }
}

IoT SIMs

serviceArea: "iot"

iot.sim.activated

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

data
{
  "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.

data
{
  "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.

data
{
  "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.

data
{
  "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.

data
{
  "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.

data
{
  "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.

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

Platform

serviceArea: "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.

data
{
  "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.

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