Skip to Content
OpenRoam Docs
Webhook events

The data or expiry usage of an eSIM reached a new band.

Delivered at least once to your webhook URL.

Delivered at least once to your webhook URL. Acknowledge with any 2xx response. A signed body with isTest: true contains synthetic data and should be handled as a connectivity check.

Header Parameters

X-OpenRoam-Webhook-Id*string

The id of the webhook subscription that delivers the event.

X-OpenRoam-Timestamp*string

When this delivery attempt was signed, in Unix seconds.

X-OpenRoam-Event-Id*string

The event's unique id, the same as eventId in the body. Deduplicate on it.

X-OpenRoam-Signature*string

Lowercase hex HMAC-SHA256 of {timestamp}.{eventId}.{raw body}, keyed with your webhook secret.

Request Body

application/json
  1. body

The esim.usage.updated webhook body.

eventId*string

The event's unique id, the same as the X-OpenRoam-Event-Id header. Deduplicate on it.

Formatuuid
eventType*string

Always esim.usage.updated.

timestamp*integer

When the event was created, in Unix seconds (whole seconds since 1970-01-01T00:00:00Z).

Formatint64
data*

The eSIM's usage.

isTest?boolean

True for a synthetic test delivery. Omitted on live events.

Response Body

The event was accepted.

Example Requests
POST/esim.usage.updated

The esim.usage.updated webhook body.

Request Body
application/json
{  "eventId": "d6703cc8-9e79-415d-ac03-a4dc7f6ab43c",  "eventType": "string",  "timestamp": 0,  "data": {    "orderId": "b3e1eced-f2bd-4d8c-9765-fbc9d1d222d5",    "orderItemId": "33207bce-c741-4896-a76b-8afcf6e4179a",    "esimStatus": "new",    "profileStatus": "empty",    "packageName": "string",    "isDataUnlimited": true,    "isSmsUnlimited": true,    "isVoiceUnlimited": true  }}
Header Parameters
{  "X-OpenRoam-Webhook-Id": "string",  "X-OpenRoam-Timestamp": "string",  "X-OpenRoam-Event-Id": "string",  "X-OpenRoam-Signature": "string"}