Webhooks

Package events

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

Package Created

package.created

Triggered when a new package has been provisioned for an eSIM.

Payload

typestringrequired

Optionspackage.created

timestampstring · date-timerequired

When the event occurred

dataobjectrequired

Show properties

packageReferencestringrequired

Package reference identifier (23-character opaque token)

profileReferencestringrequired

esimReferencestringrequired

eSIM reference identifier (18-digit opaque token)

iccidstring

planReferencestringrequired

Plan reference identifier (14-character opaque token)

countryCodestring

package.created

{
  "type": "package.created",
  "timestamp": "2026-01-24T14:30:00Z",
  "data": {
    "packageReference": "C123456XYZDUSR_A1B2C3D4",
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "iccid": "89012345678901234567",
    "planReference": "C123456XYZDUSR",
    "countryCode": "US"
  }
}

Package Activated

package.activated

Triggered when a package becomes active and ready for use.

Payload

typestringrequired

Optionspackage.activated

timestampstring · date-timerequired

When the event occurred

dataobjectrequired

Show properties

packageReferencestringrequired

Package reference identifier (23-character opaque token)

profileReferencestringrequired

esimReferencestringrequired

eSIM reference identifier (18-digit opaque token)

iccidstring

planReferencestringrequired

Plan reference identifier (14-character opaque token)

countryCodestring

package.activated

{
  "type": "package.activated",
  "timestamp": "2026-01-24T14:30:00Z",
  "data": {
    "packageReference": "C123456XYZDUSR_A1B2C3D4",
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "iccid": "89012345678901234567",
    "planReference": "C123456XYZDUSR",
    "countryCode": "US"
  }
}

Package Throttled

package.throttled

Triggered when a recurring package's data allocation has been fully consumed for the current cycle. The package transitions from active to throttled and awaits the next provider renewal. Non-recurring packages emit package.exhausted instead. The event carries the figures it implies: usedAmount at the plan capacity and remainingAmount 0, until the next renewal restores the allowance.

Payload

typestringrequired

Optionspackage.throttled

timestampstring · date-timerequired

When the event occurred

dataobjectrequired

Show properties

packageReferencestringrequired

Package reference identifier (23-character opaque token)

profileReferencestringrequired

esimReferencestringrequired

eSIM reference identifier (18-digit opaque token)

iccidstringrequired

planReferencestringrequired

Plan reference identifier (14-character opaque token)

countryCodestring | null

usedAmountnumberrequired

Amount consumed when the event fired. Equal to the plan capacity when the allowance ran out; the figure reached so far when the package ended for another reason, such as the addon being removed at the provider.

remainingAmountnumberrequired

Data left when the event fired. Zero when the allowance ran out.

unitstringrequired

Unit the amounts are expressed in, determined by the package type.

Optionsmbsecondssms

percentageUsedintegerrequired

Share of the allowance consumed when the event fired. 100 when it ran out.

package.throttled

{
  "type": "package.throttled",
  "timestamp": "2026-01-24T14:30:00Z",
  "data": {
    "packageReference": "C123456XYZDUSR_A1B2C3D4",
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "iccid": "89012345678901234567",
    "planReference": "C123456XYZDUSR",
    "countryCode": "US",
    "usedAmount": 5120,
    "remainingAmount": 0,
    "unit": "mb",
    "percentageUsed": 100
  }
}

Package Exhausted

package.exhausted

Triggered when a non-recurring package's allocation has been fully consumed. Recurring packages emit package.throttled instead. The event carries the figures it implies: usedAmount at the plan capacity and remainingAmount 0.

Payload

typestringrequired

Optionspackage.exhausted

timestampstring · date-timerequired

When the event occurred

dataobjectrequired

Show properties

packageReferencestringrequired

Package reference identifier (23-character opaque token)

profileReferencestringrequired

esimReferencestringrequired

eSIM reference identifier (18-digit opaque token)

iccidstringrequired

planReferencestringrequired

Plan reference identifier (14-character opaque token)

countryCodestring | null

usedAmountnumberrequired

remainingAmountnumberrequired

Data left when the event fired. Zero when the allowance ran out.

unitstringrequired

Unit the amounts are expressed in, determined by the package type.

Optionsmbsecondssms

percentageUsedintegerrequired

Share of the allowance consumed when the event fired. 100 when it ran out.

package.exhausted

{
  "type": "package.exhausted",
  "timestamp": "2026-01-24T14:30:00Z",
  "data": {
    "packageReference": "C123456XYZDUSR_A1B2C3D4",
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "iccid": "89012345678901234567",
    "planReference": "C123456XYZDUSR",
    "countryCode": "US",
    "usedAmount": 5120,
    "remainingAmount": 0,
    "unit": "mb",
    "percentageUsed": 100
  }
}

Package Ended

package.ended

Triggered when a package has ended. Includes the reason for ending (expired, exhausted, or manually removed).

Payload

typestringrequired

Optionspackage.ended

timestampstring · date-timerequired

When the event occurred

dataobjectrequired

Show properties

packageReferencestringrequired

Package reference identifier (23-character opaque token)

profileReferencestringrequired

esimReferencestringrequired

eSIM reference identifier (18-digit opaque token)

iccidstringrequired

planReferencestringrequired

Plan reference identifier (14-character opaque token)

countryCodestring | null

reasonstringrequired

Why the package ended

Optionsexpiredexhaustedremoved

package.ended

{
  "type": "package.ended",
  "timestamp": "2026-01-24T14:30:00Z",
  "data": {
    "packageReference": "C123456XYZDUSR_A1B2C3D4",
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "iccid": "89012345678901234567",
    "planReference": "C123456XYZDUSR",
    "countryCode": "US",
    "reason": "expired"
  }
}

Package Usage Milestone

package.usage

Triggered when a package reaches a usage threshold. Usage updates are guaranteed at 33% and 66% at minimum, on every provider and every usage feed, and are published whenever consumption advances in between. Where a network reports through more than one feed, updates reflect the combined total rather than each feed separately. The end of the allowance is signalled by package.throttled or package.exhausted, which carry the figures for that moment. Usage updates continue afterwards while the package keeps consuming at the reduced speed: usedAmount grows past the plan capacity, remainingAmount stays 0 and percentageUsed stays at 100 until the next renewal.

Payload

typestringrequired

Optionspackage.usage

timestampstring · date-timerequired

When the event occurred

dataobjectrequired

Show properties

packageReferencestringrequired

Package reference identifier (23-character opaque token)

profileReferencestringrequired

esimReferencestringrequired

eSIM reference identifier (18-digit opaque token)

iccidstringrequired

planReferencestringrequired

Plan reference identifier (14-character opaque token)

countryCodestring | null

usedAmountintegerrequired

Amount used, in the package's unit (mb for data, seconds for voice, sms for SMS)

remainingAmountinteger | nullrequired

Amount remaining, same unit as usedAmount. Null when the remaining amount cannot be determined (e.g. unmetered or unavailable from provider).

unitstringrequired

Unit of usedAmount/remainingAmount, determined by the package type

Optionsmbsecondssms

dataUsedMbinteger

Data used in MB. Data packages only, emitted solely to clients with legacy API compatibility enabled — use usedAmount instead.

dataRemainingMbinteger | null

Data remaining in MB. Data packages only, emitted solely to clients with legacy API compatibility enabled — use remainingAmount instead.

percentageUsedintegerrequired

Usage threshold percentage. Guaranteed at 33 and 66 at minimum, with updates whenever consumption advances in between. 100% is signalled by package.throttled or package.exhausted.

package.usage

{
  "type": "package.usage",
  "timestamp": "2026-01-24T14:30:00Z",
  "data": {
    "packageReference": "C123456XYZDUSR_A1B2C3D4",
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "iccid": "89012345678901234567",
    "planReference": "C123456XYZDUSR",
    "countryCode": "US",
    "usedAmount": 2560,
    "remainingAmount": 2560,
    "unit": "mb",
    "dataUsedMb": 2560,
    "dataRemainingMb": 2560,
    "percentageUsed": 66
  }
}

Package Usage Threshold Crossed

package.usage.threshold

Triggered when a package's cumulative data usage crosses a usage threshold. Fires at 33% and 66%, at most once per threshold per package. The 100% case is signalled by package.throttled or package.exhausted.

Payload

typestringrequired

Optionspackage.usage.threshold

timestampstring · date-timerequired

When the event occurred

dataobjectrequired

Show properties

packageReferencestringrequired

Package reference identifier (23-character opaque token)

profileReferencestringrequired

esimReferencestringrequired

eSIM reference identifier (18-digit opaque token)

iccidstringrequired

planReferencestringrequired

Plan reference identifier (14-character opaque token)

countryCodestring | null

thresholdPercentintegerrequired

Threshold percentage that was crossed (33 or 66).

Options3366

usedAmountnumberrequired

Cumulative amount used (MB for data, count for SMS, seconds for voice).

remainingAmountnumber | null

Amount remaining in the same unit as usedAmount. Null when not determinable.

capacityTotalnumberrequired

Total plan capacity in the same unit as usedAmount

unitstringrequired

Unit of usedAmount/remainingAmount/capacityTotal, determined by the package type

Optionsmbsecondssms

package.usage.threshold

{
  "type": "package.usage.threshold",
  "timestamp": "2026-01-24T14:30:00Z",
  "data": {
    "packageReference": "C123456XYZDUSR_A1B2C3D4",
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "iccid": "89012345678901234567",
    "planReference": "C123456XYZDUSR",
    "countryCode": "US",
    "thresholdPercent": 66,
    "usedAmount": 660,
    "remainingAmount": 340,
    "capacityTotal": 1000,
    "unit": "mb"
  }
}

Package Renewed

package.renewed

Triggered when a recurring package is renewed for a new cycle. Usage counters are reset and the package transitions back to active.

Payload

typestringrequired

Optionspackage.renewed

timestampstring · date-timerequired

When the event occurred

dataobjectrequired

Show properties

packageReferencestringrequired

Package reference identifier (23-character opaque token)

profileReferencestringrequired

esimReferencestringrequired

eSIM reference identifier (18-digit opaque token)

iccidstringrequired

planReferencestringrequired

Plan reference identifier (14-character opaque token)

countryCodestring | null

nextRenewalAtstring | null · date-time

When the next renewal cycle is scheduled

remainingAmountnumber | null

Remaining data amount after renewal (MB for data packages)

package.renewed

{
  "type": "package.renewed",
  "timestamp": "2026-01-24T14:30:00Z",
  "data": {
    "packageReference": "C123456XYZDUSR_A1B2C3D4",
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "iccid": "89012345678901234567",
    "planReference": "C123456XYZDUSR",
    "countryCode": "US",
    "nextRenewalAt": "2026-01-15T09:30:00Z",
    "remainingAmount": 0
  }
}