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 support 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",
    "apn": "netavo"
  }
}

IoT SIMs

serviceArea: "iot"

iot.sim.activated

A SIM's activation took effect on the network. Billing for the SIM starts now. apn is the APN to set on the device, or null while we have yet to confirm it.

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

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

platform.order.shipped

A consignment of an order of SIMs was despatched, with the SIMs it carries. Sent once per consignment, so an order sent in two parts sends it twice. courier is the courier's code and carrier its display name; RoyalMailUntracked (a 1st or 2nd Class letter) and HandDelivery have no tracking number.

data
{
  "orderId": "6f1d2c3b-4a59-4e8f-9b7a-1c2d3e4f5a6b",
  "shipmentId": "0b9a8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d",
  "courier": "RoyalMail",
  "carrier": "Royal Mail",
  "trackingNumber": "QF123456789GB",
  "trackingUrl": "https://www.royalmail.com/track-your-item#/tracking-results/QF123456789GB",
  "simCount": 2,
  "iccids": [
    "8944110068212345678",
    "8944110068212345686"
  ],
  "shippedAt": "2026-09-25T00:00:00Z"
}

platform.order.esims_ready

The eSIMs on an order are ready to install: their activation codes can be read from the order. The codes are never sent in the notification.

data
{
  "orderId": "6f1d2c3b-4a59-4e8f-9b7a-1c2d3e4f5a6b",
  "esimCount": 3,
  "readyAt": "2026-09-25T15:40:00Z"
}