Webhooks

eSIM events

Signed POST requests to your webhook endpoint for esim lifecycle events. See the Webhooks overview for signature verification.

eSIM Assigned

esim.assigned

Triggered when an eSIM is successfully assigned to a client after ordering. The eSIM is now ready to be downloaded to a device.

Payload

typestring

Optionsesim.assigned

timestampstring · date-time

When the event was recorded. This can be later than the change it reports: usage reported by the network can describe consumption that happened earlier.

dataobject

Show properties

profileReferencestring

esimReferencestring

eSIM reference identifier (18-digit opaque token)

iccidstring

esim.assigned

{
  "type": "esim.assigned",
  "timestamp": "2026-01-24T14:30:00Z",
  "data": {
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "iccid": "89012345678901234567"
  }
}

eSIM Downloaded

esim.downloaded

Triggered when an eSIM profile has been downloaded to a device.

Payload

typestring

Optionsesim.downloaded

timestampstring · date-time

When the event was recorded. This can be later than the change it reports: usage reported by the network can describe consumption that happened earlier.

dataobject

Show properties

profileReferencestring

esimReferencestring

eSIM reference identifier (18-digit opaque token)

iccidstringoptional

eidstringoptional

The eUICC Identifier (EID) of the device, if available

esim.downloaded

{
  "type": "esim.downloaded",
  "timestamp": "2026-01-24T14:30:00Z",
  "data": {
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "iccid": "89012345678901234567",
    "eid": "89049032000000000000000000000001"
  }
}

eSIM Installed

esim.installed

Triggered when an eSIM profile has been installed on a device.

Payload

typestring

Optionsesim.installed

timestampstring · date-time

When the event was recorded. This can be later than the change it reports: usage reported by the network can describe consumption that happened earlier.

dataobject

Show properties

profileReferencestring

esimReferencestring

eSIM reference identifier (18-digit opaque token)

iccidstringoptional

eidstringoptional

The eUICC Identifier (EID) of the device, if available

esim.installed

{
  "type": "esim.installed",
  "timestamp": "2026-01-24T14:30:00Z",
  "data": {
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "iccid": "89012345678901234567",
    "eid": "89049032000000000000000000000001"
  }
}

eSIM Enabled

esim.enabled

Triggered when an eSIM profile has been enabled on a device.

Payload

typestring

Optionsesim.enabled

timestampstring · date-time

When the event was recorded. This can be later than the change it reports: usage reported by the network can describe consumption that happened earlier.

dataobject

Show properties

profileReferencestring

esimReferencestring

eSIM reference identifier (18-digit opaque token)

iccidstringoptional

eidstringoptional

The eUICC Identifier (EID) of the device, if available

esim.enabled

{
  "type": "esim.enabled",
  "timestamp": "2026-01-24T14:30:00Z",
  "data": {
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "iccid": "89012345678901234567",
    "eid": "89049032000000000000000000000001"
  }
}

eSIM Disabled

esim.disabled

Triggered when an eSIM profile has been disabled on a device.

Payload

typestring

Optionsesim.disabled

timestampstring · date-time

When the event was recorded. This can be later than the change it reports: usage reported by the network can describe consumption that happened earlier.

dataobject

Show properties

profileReferencestring

esimReferencestring

eSIM reference identifier (18-digit opaque token)

iccidstringoptional

eidstringoptional

The eUICC Identifier (EID) of the device, if available

esim.disabled

{
  "type": "esim.disabled",
  "timestamp": "2026-01-24T14:30:00Z",
  "data": {
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "iccid": "89012345678901234567",
    "eid": "89049032000000000000000000000001"
  }
}

eSIM Deleted

esim.deleted

Triggered when an eSIM profile has been deleted from a device.

Payload

typestring

Optionsesim.deleted

timestampstring · date-time

When the event was recorded. This can be later than the change it reports: usage reported by the network can describe consumption that happened earlier.

dataobject

Show properties

profileReferencestring

esimReferencestring

eSIM reference identifier (18-digit opaque token)

iccidstringoptional

eidstringoptional

The eUICC Identifier (EID) of the device, if available

esim.deleted

{
  "type": "esim.deleted",
  "timestamp": "2026-01-24T14:30:00Z",
  "data": {
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "iccid": "89012345678901234567",
    "eid": "89049032000000000000000000000001"
  }
}

eSIM Faulted

esim.faulted

Triggered when an eSIM profile fails to download to, or install on, a device. Distinct from esim.deleted, which reports an actual removal of a profile that was present.

reason is the normalized cause and detail keeps the underlying provider codes for support. A fault is usually not the end of the attempt: the download order stays live and the device may retry to a successful install, so a subsequent esim.installed for the same eSIM is expected and supersedes this event. The exception is download_order_expired, where the order itself is dead and a replacement eSIM must be ordered.

Payload

typestring

Optionsesim.faulted

timestampstring · date-time

When the event was recorded. This can be later than the change it reports: usage reported by the network can describe consumption that happened earlier.

dataobject

Show properties

profileReferencestring

esimReferencestring

eSIM reference identifier (18-digit opaque token)

iccidstringoptional

eidstringoptional

The eUICC Identifier (EID) of the device, if available

reasonstring

Extensible enum. Normalized cause of the failure. download_order_expired means the download order ran out of attempts and is dead. user_rejected means the end user declined the installation prompt. device_out_of_memory means the device has no room for another profile. already_installed means the profile is already present on that device. install_interrupted means the installation was cut short. profile_rejected means the device could not process the profile's contents. device_unspecified_error means the device refused the installation without stating a cause of its own. download_failed and install_failed are the unclassified failures of their respective stages, and unknown is a failure the provider described with no machine-readable cause.

Examplesdownload_order_expireduser_rejecteddownload_faileddevice_out_of_memoryalready_installedinstall_interruptedprofile_rejecteddevice_unspecified_errorinstall_failedunknown

detailstringoptional

The underlying provider codes and message behind reason, for support and debugging. Free-form and not intended to be parsed. Absent when the provider supplied none.

esim.faulted

{
  "type": "esim.faulted",
  "timestamp": "2026-01-24T14:30:00Z",
  "data": {
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "iccid": "89012345678901234567",
    "eid": "89049032000000000000000000000001",
    "reason": "device_out_of_memory",
    "detail": "bppCommandId=5 errorReason=10"
  }
}

eSIM MCC Switch (Roaming)

esim.mccswitch

Triggered when an eSIM registers on a different mobile network than the one it last registered on — a change of MCC or MNC. Repeated registrations on the same network emit nothing. Carries the previous network alongside the new one; on the first registration ever observed for an eSIM the previous* fields are absent.

Payload

typestring

Optionsesim.mccswitch

timestampstring · date-time

When the event was recorded. This can be later than the change it reports: usage reported by the network can describe consumption that happened earlier.

dataobject

Show properties

profileReferencestring

esimReferencestring

eSIM reference identifier (18-digit opaque token)

iccidstringoptional

previousCountrystringoptional

ISO 3166-1 alpha-2 country code. Absent on the first registration ever observed for the eSIM.

previousMccstringoptional

Mobile Country Code. Absent on the first registration ever observed for the eSIM.

previousMncstringoptional

Mobile Network Code

newCountrystringoptional

ISO 3166-1 alpha-2 country code resolved from the MCC. Absent when the MCC is not geographically bound (satellite and other international networks, MCC 90x).

newMccstring

Mobile Country Code

newMncstringoptional

Mobile Network Code

esim.mccswitch

{
  "type": "esim.mccswitch",
  "timestamp": "2026-01-24T14:30:00Z",
  "data": {
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "iccid": "89012345678901234567",
    "previousCountry": "NL",
    "previousMcc": "204",
    "previousMnc": "08",
    "newCountry": "BE",
    "newMcc": "206",
    "newMnc": "01"
  }
}

eSIM Lifecycle Suspended

esim.lifecycle.suspended

Triggered when an eSIM's network connectivity is suspended, via PATCH /profiles/{profileReference}/esims/{esimReference}/lifecycle with operation: suspend. This is the network lifecycle, not the profile state on the device: esim.disabled reports the profile being switched off on the handset, while this event reports the SIM no longer being served by the network. Packages ordered on the eSIM stay active and send no event.

Payload

typestring

Optionsesim.lifecycle.suspended

timestampstring · date-time

When the event was recorded. This can be later than the change it reports: usage reported by the network can describe consumption that happened earlier.

dataobject

Show properties

profileReferencestring

esimReferencestring

eSIM reference identifier (18-digit opaque token)

iccidstringoptional

lifecycleStatusstring

Network lifecycle status after the change

Optionssuspended

previousLifecycleStatusstringoptional

Network lifecycle status before the change

Optionsactive

esim.lifecycle.suspended

{
  "type": "esim.lifecycle.suspended",
  "timestamp": "2026-01-24T14:30:00Z",
  "data": {
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "iccid": "89012345678901234567",
    "lifecycleStatus": "suspended",
    "previousLifecycleStatus": "active"
  }
}

eSIM Lifecycle Activated

esim.lifecycle.activated

Triggered when an eSIM's network connectivity is activated after a suspension, either via PATCH /profiles/{profileReference}/esims/{esimReference}/lifecycle with operation: reactivate, or automatically when a package is ordered on a suspended eSIM, and when a preactive eSIM goes live. Not emitted for an eSIM that is active when it is assigned; esim.assigned covers that.

Payload

typestring

Optionsesim.lifecycle.activated

timestampstring · date-time

When the event was recorded. This can be later than the change it reports: usage reported by the network can describe consumption that happened earlier.

dataobject

Show properties

profileReferencestring

esimReferencestring

eSIM reference identifier (18-digit opaque token)

iccidstringoptional

lifecycleStatusstring

Network lifecycle status after the change

Optionsactive

previousLifecycleStatusstringoptional

Network lifecycle status before the change

Optionspreactivesuspended

esim.lifecycle.activated

{
  "type": "esim.lifecycle.activated",
  "timestamp": "2026-01-24T14:30:00Z",
  "data": {
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "iccid": "89012345678901234567",
    "lifecycleStatus": "active",
    "previousLifecycleStatus": "suspended"
  }
}

eSIM Lifecycle Terminated

esim.lifecycle.terminated

Triggered when an eSIM's network connectivity is permanently terminated, via PATCH /profiles/{profileReference}/esims/{esimReference}/lifecycle with operation: terminate. Terminal: the eSIM cannot be reactivated. Any active packages are ended first, each with its own package.ended event carrying reason: removed.

Payload

typestring

Optionsesim.lifecycle.terminated

timestampstring · date-time

When the event was recorded. This can be later than the change it reports: usage reported by the network can describe consumption that happened earlier.

dataobject

Show properties

profileReferencestring

esimReferencestring

eSIM reference identifier (18-digit opaque token)

iccidstringoptional

lifecycleStatusstring

Network lifecycle status after the change

Optionsterminated

previousLifecycleStatusstringoptional

Network lifecycle status before the change

Optionspreactiveactivesuspended

esim.lifecycle.terminated

{
  "type": "esim.lifecycle.terminated",
  "timestamp": "2026-01-24T14:30:00Z",
  "data": {
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "iccid": "89012345678901234567",
    "lifecycleStatus": "terminated",
    "previousLifecycleStatus": "active"
  }
}

eSIM Balance Updated

esim.balance.updatedExperimental

Sent after a balance credit or debit succeeds.

Payload

typestring

Optionsesim.balance.updated

timestampstring · date-time

When the event was recorded. This can be later than the change it reports: usage reported by the network can describe consumption that happened earlier.

dataobject

Show properties

profileReferencestring

esimReferencestring

updateTypestring

Optionscreditdebit

sourcestring

Who originated the update: client for your own credit, debit or set; provider for a movement the network applied; system for a movement we made on our own.

Optionsclientprovidersystem

reasonstring

detailstringoptional

Optional context for this update

amountinteger

Update amount in integer minor currency units

balanceAfterinteger

Balance after this update

currencystring

Three-letter ISO 4217 currency code

clientTransactionIdstringoptional

Client transaction identifier, present for client updates

providerTransactionIdstringoptional

External transaction identifier when available

occurredAtstring · date-timeoptional

When the balance update occurred

esim.balance.updated

{
  "type": "esim.balance.updated",
  "timestamp": "2026-01-24T14:30:00Z",
  "data": {
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "updateType": "credit",
    "source": "client",
    "reason": "topup",
    "detail": "string",
    "amount": 500,
    "balanceAfter": 1500,
    "currency": "EUR",
    "clientTransactionId": "example-credit-tx-001",
    "providerTransactionId": "string",
    "occurredAt": "2026-01-15T09:30:00Z"
  }
}