API v2.3 / Callback / eSIM Usage Callback

Server eSIMGo API - https://api.esim-go.com/v2.3

POST

https://your-usage-callback-url/

• eSIMGo API

V3 of the Callback system is now available and provides additional data as well as HMAC signature validation. This must be enabled in the eSIM Portal. V2 of the Callback system is still available by default, but will be disabled in the future.

When data is used on an eSIM, a usage event can be sent to a URL defined by you in the eSIM Portal. The usage event will report the current bundle in use by an eSIM, and it’s remaining data.

Example of validating HMAC body in NodeJS:

import crypto from "crypto";

const signature = crypto
    .createHmac("sha256", key) // key is your API Key
    .update(body) // body is the raw (string) request body
    .digest("base64");

const matches = signature === signatureHeader;

Validation uses your API Key as the HMAC key. The body of the request is the raw (string) request body, and should not be parsed as JSON before validation.

Note: Bundle names are case sensitive e.g. “esim_1GB_7D_IM_U”.

Request Body Notes:

• The “try” button for this endpoint is NOT functional
• The schema defines an example message that is sent to the configured callback URL.
• For more information on callback notification types, Please see the Notifications Page.

Request Body ^required

One of:

V3 Body

object

iccid

Your eSIM ICCID value

string

alertType

Type of callback alert

string

bundle

object

id

ID of the Bundle assignment; used for removing single assignment of a Bundle from an eSIM

string

reference

Reference of the Bundle assignment; this can be used with Assignment endpoint https://docs.esim-go.com/api/#get-/esims/assignments

string

name

Name of Bundle applied to eSIM

string

description

Description of Bundle applied to eSIM

string

initialQuantity

Starting quantity of data supplied by Bundle (in Bytes)

integer format: float

remainingQuantity

Remaining quantity of data (in Bytes)

integer format: float

startTime

Start time of Bundle.

Format as defined in RFC 3339, section 5.6. Timezone is UTC (ends with ‘Z’). Example: 2006-01-02T15:04:05Z

string format: date-time

endTime

End time of Bundle.

Format as defined in RFC 3339, section 5.6. Timezone is UTC (ends with ‘Z’). Example: 2007-01-02T15:04:05Z

string format: date-time

unlimited

Whether the bundle is unlimited

boolean

V2 Body

object

iccid

Your eSIM ICCID value

string

alertType

Type of callback alert

string

bundle

object

name

Name of Bundle applied to eSIM

string

initialQuantity

Starting quantity of data supplied by Bundle (in Bytes)

integer format: float

remainingQuantity

Remaining quantity of data (in Bytes)

integer format: float

startTime

Start time of Bundle.

Format as defined in RFC 3339, section 5.6. Timezone is UTC (ends with ‘Z’). Example: 2006-01-02T15:04:05Z

string format: date-time

endTime

End time of Bundle.

Format as defined in RFC 3339, section 5.6. Timezone is UTC (ends with ‘Z’). Example: 2007-01-02T15:04:05Z

string format: date-time

Examples

{
  "iccid": "8944538532008160222",
  "alertType": "Utilisation",
  "bundle": {
    "id": "123456789",
    "name": "A_BUNDLE_20GB_30D_EU_U",
    "description": "A Bundle, 20GB, 30 Days, EU, Unthrottled",
    "initialQuantity": 20000000000,
    "remainingQuantity": 19000000000,
    "startTime": "2006-01-02T15:04:05Z",
    "endTime": "2007-01-02T15:04:05Z",
    "reference": "12345-12345-12345-12345-0",
    "unlimited": false
  }
}

{
  "iccid": "8944538532008160222",
  "alertType": "Utilisation",
  "bundle": {
    "id": "123456789",
    "name": "A_BUNDLE_20GB_30D_EU_U",
    "initialQuantity": 20000000000,
    "remainingQuantity": 19000000000,
    "startTime": "2006-01-02T15:04:05Z",
    "endTime": "2007-01-02T15:04:05Z"
  }
}