Skip to main content
A webhook allows you to receive certain events at a specified endpoint on your server, upon which you can take actions.

​
Configuring a webhook

A webhook can be created from the Bondio portal by following these steps:
  1. Go to the webhooks section on the sidebar
  2. Click New webhook at the top right
  3. Enter your server endpoint where you want to receive the webhook events
  4. Click Create

​
Sample event

{
  "type": "attachment.activated",
  "timestamp": 1730474606,
  "data": {
    "esim": "89928374298342734",
    "planId": "plan_rndmid12",
    "attachmentId": "pattch_3rnplcna"
  }
}

​
Validating the webhook signature

Each webhook call generated from Bondio contains a unique signature header to authenticate the call. The webhook contains a header bondio-signature, which identifies the call signature for each user uniquely. To validate the signature, we have created an npm library: @bondio/webhook-signature-validator 
import * as bondioSignatureValidator from '@bondio/webhook-signature-validator';

bondioSignatureValidator.validate(signature, signingKey, webhookDataObject);
FieldDescription
signatureThe header received in the bondio-signature field.
signingKeyThe key defined while registering the webhook URL on dashboard.bondio.co/home/webhooks.
webhookDataObjectThe JSON data received in the webhook call.

​
Event types

​
Subscription (V1)

​
subscription.activated

Fired when a subscription is activated.
​
type
string
required
subscription.activated
​
subscriptionId
string
required
The ID of the subscription that was activated.
​
esimIccid
string
required
The ICCID used in the subscription.
​
timestamp
integer
required
The Unix timestamp at which this event was fired.
Example
{
  "type": "subscription.activated",
  "timestamp": 1730474606,
  "subscriptionId": "subs.dbrt3472j"
}

​
subscription.allowance.thresholdBreached

Fired when a usage threshold is breached on a subscription.
​
type
string
required
subscription.allowance.thresholdBreached
​
subscriptionId
string
required
The ID of the subscription whose threshold was breached.
​
breachedService
enum
required
The service where the threshold was breached: data, voice, or sms.
​
threshold
integer
required
The percentage threshold that was breached (e.g., 80).
​
esimIccid
string
required
The ICCID used in the subscription.
​
timestamp
integer
required
The Unix timestamp at which this event was fired.
Example
{
  "type": "subscription.allowance.thresholdBreached",
  "timestamp": 1730474606,
  "subscriptionId": "subs.dbrt3472j",
  "breachedService": "data",
  "threshold": 80
}

​
Subscription V2

​
attachment.activated

Fired when a plan attachment gets activated, regardless of activation type.
​
type
string
required
attachment.activated
​
timestamp
integer
required
The Unix timestamp at which this event was fired.
​
data
object
required
Example
{
  "type": "attachment.activated",
  "timestamp": 1730474606,
  "data": {
    "esim": "89928374298342734",
    "plan": {
      "dataMegaBytes": 1024,
      "periodDays": 1,
      "periodIterations": 7,
      "throttledSpeedKbps": 128,
      "coverageProfileId": "cvpr_j64hksfs",
      "label": "tau"
    },
    "attachmentId": "pattch_3rnplcna"
  }
}

​
attachment.allowanceConsumed

This event is sent at 50%, 80% & 100% of data usage on an attachment of a fixed-validity plan. No events are sent for recurring plans.
In cases where data consumption on the eSIM is very heavy (e.g., HD streaming), the system may skip sending the 50% or 80% usage events.
​
type
string
required
attachment.allowanceConsumed
​
timestamp
integer
required
The Unix timestamp at which this event was fired.
​
data
object
required
Example
{
  "type": "attachment.allowanceConsumed",
  "timestamp": 1730474606,
  "data": {
    "usagePercentage": 80,
    "dataUsageBytes": 1231230,
    "esim": "89123465789487473",
    "planId": "plan_dy393lsf2",
    "attachmentId": "ptac_lkajsdfkll"
  }
}

​
subscriptionV2.esim.locationChanged

Sent whenever a change in the country of an eSIM is detected.
​
type
string
required
subscriptionV2.esim.locationChanged
​
timestamp
integer
required
The Unix timestamp at which this event was fired.
​
data
object
required
Example
{
  "type": "subscriptionV2.esim.locationChanged",
  "timestamp": 1738678426,
  "data": {
    "esim": "8937204017177713446",
    "countryIso2": "IN"
  }
}

​
eSIM

​
esim.smdp.stateChanged

Sent whenever the SMDP state of an eSIM is changed.
​
type
string
required
esim.smdp.stateChanged
​
timestamp
integer
required
The Unix timestamp at which this event was fired.
​
data
object
required
Example
{
  "type": "esim.smdp.stateChanged",
  "timestamp": 1738678426,
  "data": {
    "esim": "8937204017177713446",
    "smdpStateChange": {
      "state": "RELEASED",
      "modifiedAt": 17892378963,
      "modificationResult": "SUCCESS"
    }
  }
}