Event webhook

POST

Roamex posts each event to every webhook endpoint you registered in the panel for that event type. Verify X-Roamex-Signature: it is sha256= followed by the hex HMAC-SHA256 of the raw request body, keyed with the endpoint’s signing secret. Deliveries can repeat, so use id to ignore one you already handled.

Parameters

Header Parameters

X-Roamex-Event

required

• esim.provisioned: new eSIMs were provisioned.
• order.created: an order paid from your balance was created.
• esim.topped_up: an eSIM got more data or days.
• customer_topup.succeeded: a traveller paid for a top-up and received it.
• wallet.low_balance: your balance fell below your low-balance threshold.
• wallet.topped_up: your balance was topped up.
• esim.low_data: an eSIM is running low on data.
• esim.activated: an eSIM connected for the first time.
• esim.expiring_soon: an eSIM is close to its end date.

string

Allowed values: esim.provisioned order.created esim.topped_up customer_topup.succeeded wallet.low_balance wallet.topped_up esim.low_data esim.activated esim.expiring_soon

The event type.

X-Roamex-Delivery

required

string format: uuid

The delivery id, the same as id in the body.

X-Roamex-Event-Id

string format: uuid

The event id, the same as event_id in the body. Absent when event_id is null.

X-Roamex-Signature

required

string

/^sha256=[0-9a-f]{64}$/

sha256= followed by the hex HMAC-SHA256 of the raw body, keyed with the endpoint’s signing secret.

Request Body^required

Media typeapplication/json

object

id

required

The delivery id. A retry of this delivery carries the same id.

string format: uuid

event_id

required

The event id, the same as id in /events/recent. One event sent to two endpoints has one event_id.

string | null format: uuid

type

required

• esim.provisioned: new eSIMs were provisioned.
• order.created: an order paid from your balance was created.
• esim.topped_up: an eSIM got more data or days.
• customer_topup.succeeded: a traveller paid for a top-up and received it.
• wallet.low_balance: your balance fell below your low-balance threshold.
• wallet.topped_up: your balance was topped up.
• esim.low_data: an eSIM is running low on data.
• esim.activated: an eSIM connected for the first time.
• esim.expiring_soon: an eSIM is close to its end date.

string

Allowed values: esim.provisioned order.created esim.topped_up customer_topup.succeeded wallet.low_balance wallet.topped_up esim.low_data esim.activated esim.expiring_soon

created_at

required

When the event happened. The same on every attempt.

string format: date-time

sent_at

required

When this attempt was sent.

string format: date-time

data

required

The event’s fields. They depend on the event type.

object

key

additional properties

any

Example

{
  "id": "00000000-0000-4000-8000-0000000000f1",
  "event_id": "00000000-0000-4000-8000-0000000000e1",
  "type": "esim.topped_up",
  "created_at": "2026-10-22T09:12:00.000Z",
  "sent_at": "2026-10-22T09:13:05.000Z",
  "data": {
    "esim_id": "00000000-0000-4000-8000-0000000000c1",
    "iccid": "8900000000000000000",
    "package_name": "Japan · 1 GB · 7 days",
    "volume_bytes": 1073741824,
    "duration": 7,
    "duration_unit": "DAY",
    "cost_minor": 450,
    "currency": "EUR",
    "new_balance_minor": 23650
  }
}

Responses

2XX

Any 2xx answer marks the delivery done. Anything else, no answer within 10 seconds or a redirect counts as a failed attempt. A delivery gets up to 6 attempts, retried after 1, 5, 15, 60 and 360 minutes.