Event catalog

Every async state change in heliumOS emits a webhook event. This catalog enumerates the event types you can subscribe to; payload shapes are documented in the API reference under the Events tag. The authoritative, always-current list is served at GET /v1/reference/event_types, and webhook endpoint enabled_events is validated against it.

Shape

Every event carries:

{
  "id": "evt_...",
  "type": "sim.activated",
  "created_at": "2026-04-24T15:00:00Z",
  "livemode": false,
  "data": { "object": { ... } },
  "idempotency_key": "..."
}

Subscriber events

Subscriber event payloads are always PII-redacted: email, phone, and date_of_birth are null and the object carries pii_redacted: true. Read the subscriber back through GET /v1/subscribers/{id} (subject to your role's PII permissions) when you need the contact fields.

Subscription events

SIM events

The eSIM install code rides sim.provisioned, sim.activated and sim.swapped — but only for an endpoint that subscribes to them on purpose. The activation_code (LPA) string installs the subscriber's profile onto whatever device scans it, so it is delivered only where enabled_events names the type directly (sim.*, or the exact type). An endpoint left on the default catch-all * still receives every one of these events; the activation_code field is simply absent from the body.

Building an eSIM flow? Subscribe with sim.* rather than *. Wiring up an analytics sink or a general-purpose connector? * is the right choice, and it keeps install credentials out of it.

Port events

Usage events

Billing events

pSIM order events

The recipient email and shipping_address are redacted in the event store and injected into the outbound webhook body at delivery time, so your fulfilment backend receives a complete order.

CPNI step-up events

When a support agent needs to view a subscriber's PII or change their account, heliumOS issues a one-time verification code and asks you to deliver it to the subscriber over your own channel (SMS, app push, email). The subscriber reads it back to the agent, who enters it to unlock access for a window.

cpni.verification.requested is the only event whose payload contains a secret: data.object.code. Deliver it to the subscriber and treat it like a password: don't log it, and don't store it. The code is short-lived (operator-configured, default 10 minutes) and is never returned by the GET /events API; it rides the signed webhook only.

{
  "type": "cpni.verification.requested",
  "data": {
    "object": {
      "object": "cpni_verification",
      "id": "cpniv_01HGZX...",
      "subscriber_id": "sbr_01HGZX...",
      "agent": { "user_id": "...", "email": "agent@operator.example" },
      "code": "482913",
      "expires_at": "2026-06-08T17:10:00Z",
      "grant_duration_seconds": 1800
    }
  }
}

Carrier connection events

Event types are additive: new types may appear without a major version bump. Handlers should ignore unknown type values.