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.

SIM inventory events

The pool of unassigned cards an operator loads and activations draw from.

Port events

Catalog events

The plans and addons an operator sells. Emitted in the same transaction as the catalog write, and the payload is the full public object — an integration mirroring the catalog can upsert straight from the event rather than re-reading it, and hears a price change the moment it is made.

Usage events

Billing events

Which subscriptions get an invoice.upcoming

Every subscription is billed by one of two things: heliumOS's own billing engine, or the payment processor behind it. That is what decides whether you get a pre-renewal notice.

• Sandbox subscriptions are billed by heliumOS, always. They get an invoice.upcoming three days before the cycle turns over, and the amount on it is the renewal's own arithmetic — every seat on a family plan, the add-ons falling due on this cycle, and any credit carried over from a mid-cycle change. It is a pre-tax figure: tax is assessed when the invoice is actually raised.
• Live subscriptions move onto heliumOS's billing engine in stages, a subscription at a time rather than a whole environment at once, so one live environment can hold both kinds. One that has moved gets the same notice as a sandbox subscription. One the payment processor still bills gets none, because the processor, not heliumOS, is the only thing that can say what its next bill will be. Nothing about the payload changes when a subscription moves.

If you want a heads-up on a live subscription today, poll GET /v1/subscriptions/{id}/renewal, which answers the same question on demand.

Emailing the bill: wait for invoice.document_ready

heliumOS does not send email or SMS to your subscribers — you do, on your own channels, with your own wording. Two fields on the invoice are what you send them:

• hosted_invoice_url — a page your customer can open with no login, safe to put in an email or an SMS.
• document_url — the PDF of the same bill, on the same link.

Both are signed and valid for 90 days. Read them fresh from the API when you send rather than storing them, and your links are always current; a link that has aged out answers 410 with a plain page telling the reader to ask you for a new one.

The catch is timing. invoice.finalized fires the instant the bill is frozen, and the PDF is rendered moments later — so an invoice fetched on invoice.finalized can still carry document_url: null. invoice.document_ready is the event that says the document exists. Send on that one, and both fields are populated on the invoice object it carries.

Invoices issued before heliumOS began rendering documents have no document_url, and their hosted_invoice_url is the payment provider's own page — which expires on the provider's schedule, not ours.

Dispute events

A cardholder disputed a charge with their bank — a chargeback.

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.

SMS events

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.

The cpni.escalation.* events carry no personal data and no code.

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

Team hand-offs: submitted_by

data.object.agent on every cpni.verification.* event is the agent who requested the challenge. When your operator shares verified access across the support team, a teammate can take over the chat and enter the code the subscriber reads back. On cpni.verification.succeeded and cpni.verification.failed, a submitted_by object then names the agent who entered the code (or, on a failure, the wrong codes). It is present only when that agent differs from agent; when the requester entered the code themselves, the field is omitted.

{
  "type": "cpni.verification.succeeded",
  "data": {
    "object": {
      "object": "cpni_verification",
      "id": "cpniv_01HGZX...",
      "status": "verified",
      "agent": { "user_id": "...", "email": "first-agent@operator.example" },
      "submitted_by": { "user_id": "...", "email": "second-agent@operator.example" }
    }
  }
}

The dashboard's verification log records who entered the correct code as Completed by, including when that was the requesting agent.

Referral events

Only fire when the referrals product is switched on for your operator.

Payloads carry public ids and no personal data about either party. Changes to a referral offer are operator configuration and are audited in the dashboard rather than broadcast. See the Referrals guide.

Carrier connection events

Payment connection events

Fire only when a scheduled check finds the connection's status has changed; previous_attributes carries the old status.

Fraud screening events

Fraud screening is enabled per operator. These events only fire for an operator it has been turned on for; ask your heliumOS contact to enable it.

Webhook endpoint events

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