Firsty

Search...

Search...

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

typestringrequired
Optionsesim.assigned
timestampstring · date-timerequired

When the event occurred

dataobjectrequired
Show properties
profileReferencestringrequired
esimReferencestringrequired

eSIM reference identifier (18-digit opaque token)

iccidstringrequired
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

typestringrequired
Optionsesim.downloaded
timestampstring · date-timerequired

When the event occurred

dataobjectrequired
Show properties
profileReferencestringrequired
esimReferencestringrequired

eSIM reference identifier (18-digit opaque token)

iccidstring
eidstring

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

typestringrequired
Optionsesim.installed
timestampstring · date-timerequired

When the event occurred

dataobjectrequired
Show properties
profileReferencestringrequired
esimReferencestringrequired

eSIM reference identifier (18-digit opaque token)

iccidstring
eidstring

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

typestringrequired
Optionsesim.enabled
timestampstring · date-timerequired

When the event occurred

dataobjectrequired
Show properties
profileReferencestringrequired
esimReferencestringrequired

eSIM reference identifier (18-digit opaque token)

iccidstring
eidstring

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

typestringrequired
Optionsesim.disabled
timestampstring · date-timerequired

When the event occurred

dataobjectrequired
Show properties
profileReferencestringrequired
esimReferencestringrequired

eSIM reference identifier (18-digit opaque token)

iccidstring
eidstring

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

typestringrequired
Optionsesim.deleted
timestampstring · date-timerequired

When the event occurred

dataobjectrequired
Show properties
profileReferencestringrequired
esimReferencestringrequired

eSIM reference identifier (18-digit opaque token)

iccidstring
eidstring

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

Experimental. This event is still settling — its payload may change without a deprecation cycle.

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

typestringrequired
Optionsesim.faulted
timestampstring · date-timerequired

When the event occurred

dataobjectrequired
Show properties
profileReferencestringrequired
esimReferencestringrequired

eSIM reference identifier (18-digit opaque token)

iccidstring
eidstring

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

reasonstringrequired

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

Optionsdownload_order_expireduser_rejecteddownload_faileddevice_out_of_memoryalready_installedinstall_interruptedinstall_failedunknown
detailstring

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

typestringrequired
Optionsesim.mccswitch
timestampstring · date-timerequired

When the event occurred

dataobjectrequired
Show properties
profileReferencestringrequired
esimReferencestringrequired

eSIM reference identifier (18-digit opaque token)

iccidstring
previousCountrystring

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

previousMccstring

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

previousMncstring

Mobile Network Code

newCountrystring

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).

newMccstringrequired

Mobile Country Code

newMncstring

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 line no longer being served by the network. Any active packages are ended first, each with its own package.ended event carrying reason: removed.

Payload

typestringrequired
Optionsesim.lifecycle.suspended
timestampstring · date-timerequired

When the event occurred

dataobjectrequired
Show properties
profileReferencestringrequired
esimReferencestringrequired

eSIM reference identifier (18-digit opaque token)

iccidstring
lifecycleStatusstringrequired

Network lifecycle status after the change

Optionssuspended
previousLifecycleStatusstring

Network lifecycle status before the change

Optionsactivesuspendedterminated
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. Not emitted when an eSIM first goes live after provisioning: esim.assigned covers that.

Payload

typestringrequired
Optionsesim.lifecycle.activated
timestampstring · date-timerequired

When the event occurred

dataobjectrequired
Show properties
profileReferencestringrequired
esimReferencestringrequired

eSIM reference identifier (18-digit opaque token)

iccidstring
lifecycleStatusstringrequired

Network lifecycle status after the change

Optionsactive
previousLifecycleStatusstring

Network lifecycle status before the change

Optionsactivesuspendedterminated
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

typestringrequired
Optionsesim.lifecycle.terminated
timestampstring · date-timerequired

When the event occurred

dataobjectrequired
Show properties
profileReferencestringrequired
esimReferencestringrequired

eSIM reference identifier (18-digit opaque token)

iccidstring
lifecycleStatusstringrequired

Network lifecycle status after the change

Optionsterminated
previousLifecycleStatusstring

Network lifecycle status before the change

Optionsactivesuspendedterminated
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.updated

Experimental. This event is still settling — its payload may change without a deprecation cycle.

Sent after a balance credit or debit succeeds.

Payload

typestringrequired
Optionsesim.balance.updated
timestampstring · date-timerequired

When the event occurred

dataobjectrequired
Show properties
profileReferencestringrequired
esimReferencestringrequired
updateTypestringrequired
Optionscreditdebit
sourcestringrequired
Optionsclientprovider
reasonstringrequired
detailstring

Optional context for this update

amountintegerrequired

Update amount in integer minor currency units

balanceAfterintegerrequired

Balance after this update

currencystringrequired

Three-letter ISO 4217 currency code

clientTransactionIdstring

Client transaction identifier, present for client updates

providerTransactionIdstring

External transaction identifier when available

occurredAtstring · date-time

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