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 package order is accepted. Provisioning may still be pending; package.activated confirms completion.

Payload

typestring

Optionspackage.created

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

packageReferencestring

Package reference identifier (23-character opaque token)

profileReferencestring

esimReferencestring

eSIM reference identifier (18-digit opaque token)

iccidstringoptional

planReferencestring

Plan reference identifier (14-character opaque token)

countryCodestringoptional

Country or region code of the package's plan, as the plan's countryCode (e.g. 'NL', 'EU', 'global')

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 once, when the package becomes usable on the network. A package that ends, or whose allowance is used up, before it became usable never sends it: package.exhausted or package.ended can then arrive without a preceding package.activated.

Payload

typestring

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

packageReferencestring

Package reference identifier (23-character opaque token)

profileReferencestring

esimReferencestring

eSIM reference identifier (18-digit opaque token)

iccidstringoptional

planReferencestring

Plan reference identifier (14-character opaque token)

countryCodestringoptional

Country or region code of the package's plan, as the plan's countryCode (e.g. 'NL', 'EU', 'global')

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 package can no longer use its full-speed allowance and keeps service at reduced speed. The package transitions from active to throttled. This applies to recurring packages, which stay throttled until package.renewed restores the allowance, and to one-off plans with a reduced-speed tail (throttleSpeedKbps on the plan), which never renew and stay throttled until package.ended with reason: expired. Other one-off packages send package.exhausted instead. Usually the allowance was used up: usedAmount is at the plan capacity, remainingAmount 0 and percentageUsed 100. It also fires when the network withdraws the allowance before it is used up; the figures then report what was actually used. Fires at most once per cycle.

Payload

typestring

Optionspackage.throttled

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

packageReferencestring

Package reference identifier (23-character opaque token)

profileReferencestring

esimReferencestring

eSIM reference identifier (18-digit opaque token)

iccidstring

planReferencestring

Plan reference identifier (14-character opaque token)

countryCodestringoptional

Country or region code of the package's plan, as the plan's countryCode (e.g. 'NL', 'EU', 'global')

usedAmountnumber

Amount consumed when the event fired, in unit. Equal to the plan capacity when the allowance was used up; what was actually used when the network withdrew the allowance before it was used up.

remainingAmountnumber

Amount left when the event fired, in unit. Zero when the allowance was used up.

unitstring

Extensible enum. Unit a package's amounts are expressed in, determined by the package type: mb for data, seconds for voice and sms for text messages.

Examplesmbsecondssms

percentageUsedinteger

Share of the allowance consumed when the event fired, 0-100. 100 when it was used up.

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 one-off package's allowance is gone and the package no longer provides service. Recurring packages and one-off plans with a reduced-speed tail send package.throttled instead. Usually the allowance was used up: usedAmount is at the plan capacity, remainingAmount 0 and percentageUsed 100. It also fires when the network withdraws the allowance before it is used up; the figures then report what was actually used. Terminal and sent once, always together with package.ended with reason: exhausted.

Payload

typestring

Optionspackage.exhausted

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

packageReferencestring

Package reference identifier (23-character opaque token)

profileReferencestring

esimReferencestring

eSIM reference identifier (18-digit opaque token)

iccidstring

planReferencestring

Plan reference identifier (14-character opaque token)

countryCodestringoptional

Country or region code of the package's plan, as the plan's countryCode (e.g. 'NL', 'EU', 'global')

usedAmountnumber

Amount consumed when the event fired, in unit. Equal to the plan capacity when the allowance was used up; what was actually used when the network withdrew the allowance before it was used up.

remainingAmountnumber

Amount left when the event fired, in unit. Zero when the allowance was used up.

unitstring

Extensible enum. Unit a package's amounts are expressed in, determined by the package type: mb for data, seconds for voice and sms for text messages.

Examplesmbsecondssms

percentageUsedinteger

Share of the allowance consumed when the event fired, 0-100. 100 when it was used up.

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. Terminal and sent at most once per package; act on this event for the end of a package's life. reason: exhausted comes together with package.exhausted; reason: expired means the validity period ended, for a throttled package as well; reason: removed covers both a package removal and the termination of its eSIM.

Payload

typestring

Optionspackage.ended

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

packageReferencestring

Package reference identifier (23-character opaque token)

profileReferencestring

esimReferencestring

eSIM reference identifier (18-digit opaque token)

iccidstring

planReferencestring

Plan reference identifier (14-character opaque token)

countryCodestringoptional

Country or region code of the package's plan, as the plan's countryCode (e.g. 'NL', 'EU', 'global')

reasonstring

Extensible enum. Why the package ended. expired means its validity period ended. exhausted means its allowance is gone; it comes together with package.exhausted. removed means the package was removed, or its eSIM was terminated.

Examplesexpiredexhaustedremoved

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 Updated

package.usage

Triggered as consumption advances: whenever the package's total usage grows by at least one whole unit (MB, second or SMS), and on each 33% and 66% crossing. Each update reports the running total, not a delta. 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

typestring

Optionspackage.usage

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

packageReferencestring

Package reference identifier (23-character opaque token)

profileReferencestring

esimReferencestring

eSIM reference identifier (18-digit opaque token)

iccidstring

planReferencestring

Plan reference identifier (14-character opaque token)

countryCodestringoptional

Country or region code of the package's plan, as the plan's countryCode (e.g. 'NL', 'EU', 'global')

usedAmountinteger

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

remainingAmountinteger | null

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

unitstring

Extensible enum. Unit a package's amounts are expressed in, determined by the package type: mb for data, seconds for voice and sms for text messages.

Examplesmbsecondssms

percentageUsedinteger

Share of the allowance used, 0-100. Stays at 100 while a throttled package keeps consuming at reduced speed. The moment the allowance is used up 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",
    "percentageUsed": 66
  }
}

Package Usage Threshold Crossed

package.usage.threshold

Triggered when a package's cumulative usage crosses a usage threshold. Fires at 33% and 66%, at most once per threshold per renewal cycle. The 100% case is signalled by package.throttled or package.exhausted; a single usage update that uses up the allowance sends only that event, so a threshold it jumps over is not reported.

Payload

typestring

Optionspackage.usage.threshold

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

packageReferencestring

Package reference identifier (23-character opaque token)

profileReferencestring

esimReferencestring

eSIM reference identifier (18-digit opaque token)

iccidstring

planReferencestring

Plan reference identifier (14-character opaque token)

countryCodestringoptional

Country or region code of the package's plan, as the plan's countryCode (e.g. 'NL', 'EU', 'global')

thresholdPercentinteger

Threshold percentage that was crossed (33 or 66).

Options3366

usedAmountnumber

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

remainingAmountnumber | null

Amount remaining in the same unit as usedAmount.

capacityTotalnumber

Total plan capacity in the same unit as usedAmount

unitstring

Extensible enum. Unit a package's amounts are expressed in, determined by the package type: mb for data, seconds for voice and sms for text messages.

Examplesmbsecondssms

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

typestring

Optionspackage.renewed

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

packageReferencestring

Package reference identifier (23-character opaque token)

profileReferencestring

esimReferencestring

eSIM reference identifier (18-digit opaque token)

iccidstring

planReferencestring

Plan reference identifier (14-character opaque token)

countryCodestringoptional

Country or region code of the package's plan, as the plan's countryCode (e.g. 'NL', 'EU', 'global')

nextRenewalAtstring | null · date-time

When the next renewal cycle is scheduled

remainingAmountnumber | null

Allowance remaining after the renewal, in the package's unit (MB for data, seconds for voice, SMS count for SMS)

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