Webhooks & Callbacks

eSIM Go can send real-time notifications to an endpoint you control whenever events occur on your account — eSIM usage, balance changes, lifecycle events, and more. This guide covers how to set up your callback URL, choose the right callback version, and verify incoming requests.

Setting up your callback URL

1. Log in to the eSIM Go Portal
2. Navigate to Account Settings → API Details
3. Enter your endpoint URL in the Callback URL field
4. Set Callback Version to V3 (see below)

Your endpoint must be publicly accessible and respond to HTTPS POST requests.

Callback versions

There are two callback versions. V3 is recommended — V2 will be deprecated in a future release.

	V2	V3
Authentication	None	HMAC-SHA256 signature
Bundle fields	Basic	Extended (includes id, reference, description, unlimited)

Switch to V3 in the portal under Account Settings → API Details → Callback Version.

Verifying callbacks (V3)

V3 callbacks include an X-Signature-SHA256 header containing an HMAC-SHA256 hash of the raw request body, signed with your API key.

Always verify this signature before processing a callback to confirm it originated from eSIM Go.

const crypto = require('crypto');

function verifySignature(rawBody, signatureHeader, apiKey) {
  const hmac = crypto.createHmac('sha256', apiKey);
  hmac.update(rawBody);
  const expected = hmac.digest('hex');
  return expected === signatureHeader;
}

// Express example
app.post('/callback', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-signature-sha256'];
  const isValid = verifySignature(req.body, signature, process.env.ESIMGO_API_KEY);

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);
  // handle event...
  res.sendStatus(200);
});

Caution

Use the raw request body (before JSON parsing) when computing the HMAC. Parsing and re-serialising the JSON may change whitespace and cause signature mismatches.

Responding to callbacks

Return a 2xx HTTP status code to acknowledge receipt. eSIM Go considers any non-2xx response a delivery failure.

Notification types

eSIM Go sends the following event types to your callback URL:

Event	Trigger
eSIM Usage	Data used reaches 1%, 50%, 80%, or 100% of a bundle
First Attachment	eSIM connects to a network for the first time
First Use	eSIM uses data for the first time
Location Update	eSIM registers in a new country
Balance Notification	Account balance crosses a threshold
Topup	Account balance is topped up
eSIM Deletion Scheduled	eSIM flagged for deletion after 180 days inactivity
eSIM Deleted	eSIM permanently deactivated
MSISDN Enabled	Voice or SMS bundle added to an eSIM
MSISDN Disabled	Voice or SMS bundle expired or depleted

For full payload schemas for each event type, see the Notifications API reference.