Webhook Events

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:

Go to the webhooks section on the sidebar
Click New webhook at the top right
Enter your server endpoint where you want to receive the webhook events
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);

Field	Description
`signature`	The header received in the `bondio-signature` field.
`signingKey`	The key defined while registering the webhook URL on dashboard.bondio.co/home/webhooks.
`webhookDataObject`	The JSON data received in the webhook call.

Event types

Subscription (V1)

`subscription.activated`

Fired when a subscription is activated.

string

required

subscription.activated

string

required

The ID of the subscription that was activated.

string

required

The ICCID used in the subscription.

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.

string

required

subscription.allowance.thresholdBreached

string

required

The ID of the subscription whose threshold was breached.

enum

required

The service where the threshold was breached: data, voice, or sms.

integer

required

The percentage threshold that was breached (e.g., 80).

string

required

The ICCID used in the subscription.

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.

string

required

attachment.activated

integer

required

The Unix timestamp at which this event was fired.

object

required

Show properties

string

required

The eSIM ICCID.

object

required

The plan object with dataMegaBytes, periodDays, periodIterations, throttledSpeedKbps, coverageProfileId, and label.

string

required

The ID of the plan attachment.

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.

string

required

attachment.allowanceConsumed

integer

required

The Unix timestamp at which this event was fired.

object

required

Show properties

number

required

The percentage of the allowance consumed (0–100).

number

required

Total data usage in bytes.

string

required

The eSIM ICCID.

object

The plan object with dataMegaBytes, periodDays, periodIterations, throttledSpeedKbps, coverageProfileId, and label.

string

required

The ID of the plan attachment.

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.

string

required

subscriptionV2.esim.locationChanged

integer

required

The Unix timestamp at which this event was fired.

object

required

Show properties

string

required

The eSIM ICCID.

string

required

The ISO2 code of the new country.

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.

string

required

esim.smdp.stateChanged

integer

required

The Unix timestamp at which this event was fired.

object

required

Show properties

string

required

The eSIM ICCID.

object

required

Contains state (e.g., RELEASED), modifiedAt (Unix timestamp), and modificationResult (e.g., SUCCESS).

Example

{
  "type": "esim.smdp.stateChanged",
  "timestamp": 1738678426,
  "data": {
    "esim": "8937204017177713446",
    "smdpStateChange": {
      "state": "RELEASED",
      "modifiedAt": 17892378963,
      "modificationResult": "SUCCESS"
    }
  }
}

Getting Started

Endpoints

Configuring a webhook

Sample event

Validating the webhook signature

Event types

Subscription (V1)

`subscription.activated`

`subscription.allowance.thresholdBreached`

Subscription V2

`attachment.activated`

`attachment.allowanceConsumed`

`subscriptionV2.esim.locationChanged`

eSIM

`esim.smdp.stateChanged`

​Configuring a webhook

​Sample event

​Validating the webhook signature

​Event types

​Subscription (V1)

​subscription.activated

​subscription.allowance.thresholdBreached

​Subscription V2

​attachment.activated

​attachment.allowanceConsumed

​subscriptionV2.esim.locationChanged

​eSIM

​esim.smdp.stateChanged

Configuring a webhook

Sample event

Validating the webhook signature

Event types

Subscription (V1)

`subscription.activated`

`subscription.allowance.thresholdBreached`

Subscription V2

`attachment.activated`

`attachment.allowanceConsumed`

`subscriptionV2.esim.locationChanged`

eSIM

`esim.smdp.stateChanged`