API v2.5 / Callback / eSIM Usage Callback
POST /your-usage-callback-url/
Note: 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.
To enable it on the eSIM Portal go to Account Settings -> API Details -> Callback Version.
Description: The eSIMGo API offers a callback functionality that provides real-time notifications about eSIM activity, including data consumption and balance. This feature allows for tracking usage, automating responses, and customizing notifications, enhancing customer account management. Key benefits include real-time updates, usage tracking, automated responses, and customizable notifications. 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 its remaining data.
To set up the URL in the eSIM Portal go to Account Settings -> API Details -> Callback URL.
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
object
The ICCID (Integrated Circuit Card Identifier) of the SIM card
The type of alert being sent
object
Unique identifier for the bundle
Reference code for the bundle
Name of the bundle
Description of the bundle
The initial quantity the bundle had (in bytes)
The remaining quantity the bundle had (in bytes)
Start time of the bundle validity
End time of the bundle validity
Indicates if the bundle has unlimited usage
Example
{ "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 }}Responses
200
Successful response