Hubby API (2.0.0)

Welcome to the Hubby API documentation. This API enables partners to seamlessly integrate eSIM booking and management capabilities into their applications.

Key Features:

Create and manage eSIM bookings for your customers
Access our global package catalog with country-specific offerings
Track booking statuses and package activations
Support for multiple package types (starter, data-limited, unlimited, time-limited)

Package Types

The API supports four types of packages:

Starter packages: Hybrid packages that are both data and time limited. They provide a small data allowance within a short time period (default: 2 days). Perfect for first-time users and trials.
Data-limited packages: Traditional packages with a specific data allowance that expires after a certain period (default: 365 days). This is the primary package type and the default for most use cases.
Unlimited packages: Packages that provide unrestricted data usage for a specified duration. Subject to fair use policy. Ideal for heavy data users and digital nomads.
Time-limited packages: Packages that provide a fixed data allowance for a specific duration with full-speed access. These packages expire when either the data limit or time limit is reached.

Note: Top-ups are always data-limited packages, regardless of the original package type.

Authentication: All API requests must include the following headers:

x-api-key: Your public API key
x-timestamp: Current Unix timestamp in milliseconds
x-signature: HMAC-SHA256 signature

The HMAC signature must be generated for each request using:

Concatenate: timestamp + HTTP method + request path Example: "1678901234GET/bookings"
Generate HMAC-SHA256 using your secret key
Convert to hex string

Note: Swagger UI cannot be used to test the API directly as each request requires a unique HMAC signature. Please implement the authentication in your client application.

Example Node.js Implementation:

const cryptoJs = require('crypto-js');

// Configuration values that would normally come from environment
const secretKey = "YOUR_API_SECRET";
const publicKey = "YOUR_API_KEY";
const baseUrl = "YOUR_BASE_URL";

// Function to generate headers for API request
function generateApiHeaders(method, path) {
    //Timestamp is in milliseconds e.g. 1715558400000
    const timestamp = Math.floor(Date.now()).toString();

    // Ensure url is a string
    let path = String(url);

    // Remove baseUrl from the url if present
    path = processedUrl.replace(baseUrl, '');

    // Create query string if needed
    const queryString = new URL(url).search;
    if (queryString) {
        processedUrl += queryString;
    }

    // Validate public key
    if (!publicKey) {
        throw new Error("Public key is required");
    }

    // Create the payload
    // Sample payload: 1715558400000GET/bookings?bookingId=1234567890
    const payload = timestamp + method + path;

    // Generate the HMAC signature
    const signature = cryptoJs.HmacSHA256(payload, secretKey).toString(cryptoJs.enc.Hex);

    // Return headers object
    return {
        'x-timestamp': timestamp,
        'x-signature': signature,
        'x-api-key': publicKey,
        'Accept': 'application/json'
    };
}

Webhook Delivery Authentication

When Hubby delivers a webhook to your endpoint, the request carries your API key in a header. By default this is x-api-key: <your-key>. If your endpoint expects the key under a different header, the header name is configurable per partner (for example Authorization) with an optional value prefix (for example Bearer , producing Authorization: Bearer <your-key>). The default remains x-api-key with no prefix — contact support@hubbyesim.com to change it.

Signature verification

When a signing secret is configured, every webhook is signed so you can verify it originated from Hubby and was not altered in transit. Each delivery carries these headers:

x-hubby-signature — one or more comma-separated sha256=<hex> values. Verify by recomputing HMAC-SHA256(secret, "{timestamp}.{body}"), hex-encoding the result, and accepting the request if it matches any entry in the list. Signatures are lowercase hex. Treat this as a list from day one: today we send a single signature, but the list form lets us add a second signature during a future secret rotation without any change on your side.
x-hubby-timestamp — the signing timestamp, in epoch seconds. This is the {timestamp} in the signed string above.

The signed string is the timestamp, a literal ., then the exact raw request body as received. Verify against the raw bytes — do not re-serialize the JSON first, as key reordering or whitespace changes will break the match.

Reject the request if now - x-hubby-timestamp exceeds your tolerance window (we recommend ~5 minutes). This is your protection against replayed requests.

A secret stays valid until it is regenerated; there is no scheduled expiry. Regeneration is a hard cutover — update your stored secret at the same time. You receive separate secrets for staging and production.

Idempotency & event identity

Two identifiers accompany every delivery, both as headers and inside the JSON body (in case reading custom headers is awkward in your stack):

x-hubby-event-id / event_id — a stable identifier for the logical event. It stays identical across retries and across any replay of the same event, so deduplicate on it: processing the same event_id more than once should be a no-op on your side.
x-hubby-delivery-id / delivery_id — identifies a single delivery. Quote it when contacting support about a specific delivery. A replay of an event carries the same event_id but a new delivery_id.

Delivery, retries & replay

A delivery is considered successful when your endpoint returns any 2xx status.
If your endpoint returns 5xx or 429, times out, or is unreachable, Hubby retries with exponential backoff over a few hours (up to 12 attempts total).
A 4xx (other than 429) is treated as a permanent rejection of the content and is not retried. Return 2xx for "received" and reserve 4xx for genuinely malformed requests.
Every delivery is recorded and any past event can be replayed to you on request. A replay carries the same event_id (so your dedup keeps it safe) with a fresh signature and timestamp.
Deliveries are independent and ordering is not guaranteed; rely on event_id for deduplication rather than on arrival order.

Need Help?

Technical Support: support@hubbyesim.com

Download OpenAPI description

openapi.json

openapi.yaml

Servers

Mock server

https://docs.hubbyesim.com/_mock/apis/v2_0_0/openapi/

Production server

https://api.hubbyesim.com/api/

Staging server

https://api-staging.hubby.dev/api/

Booking

Operations

Package

Operations

Country

Operations

PromoCode

Operations

eSIM

Operations

WebView

Operations

Native API

Operations

Webhooks

package.usage.50_percentWebhook

Request

Triggered per package when 50% of the package's data has been consumed (data-limited) or 50% of the package's duration has elapsed (time-limited).

Bodyapplication/json

eventstringrequired

Event type identifier

Example: "package.usage.50_percent"

timestampstring(date-time)required

ISO 8601 UTC timestamp of when the event occurred. This is a body field for convenience and is distinct from the x-hubby-timestamp signing header (epoch seconds). On a replay this reproduces the original event time.

dataobjectrequired

Per-package usage event data. These events are emitted per package, not per eSIM. For data-limited packages, thresholds are based on data consumption. For time-limited packages, thresholds are based on duration elapsed.

data.external_user_idstring

Partner's own user identifier

Example: "partner_user_456"

data.booking_idstring

Booking ID

Example: "booking_abc"

data.package_idstring

The specific package that triggered the event

Example: "pkg_xyz"

data.destinationstring

ISO country code

Example: "GR"

data.sizestring

Package size (data-limited packages only)

Example: "1GB"

data.package_typestring

Type of package

Enum"data-limited""time-limited""unlimited""starter"

Example: "data-limited"

data.used_bytesinteger

Bytes consumed so far (data-limited packages)

Example: 858993459

data.remaining_bytesinteger

Bytes remaining (data-limited packages)

Example: 214748365

data.duration_daysinteger

Total package validity in days (time-limited packages)

Example: 30

data.elapsed_daysinteger

Days elapsed since activation (time-limited packages)

Example: 24

data.remaining_daysinteger

Days remaining (time-limited packages)

Example: 6

data.usage_percentinteger

Usage percentage that triggered this event (50, 80, or 100). Represents data consumed (data-limited) or duration elapsed (time-limited).

Example: 80

event_idstringrequired

Stable identifier for the logical event, also sent as the x-hubby-event-id header. Identical across retries and replays of the same event — deduplicate on it. Derived deterministically as {event}:{entity_id}.

Example: "package.usage.50_percent:pkg_xyz"

delivery_idstringrequired

Identifier for this single delivery, also sent as the x-hubby-delivery-id header. A replay of the same event carries the same event_id but a new delivery_id.

Example: "dlv_2f1c8e9a-7b3d-4a52-9c10-1e6b2f0a4d77"

application/json

{
  "event": "package.usage.50_percent",
  "timestamp": "2019-08-24T14:15:22Z",
  "data": {
    "external_user_id": "partner_user_456",
    "booking_id": "booking_abc",
    "package_id": "pkg_xyz",
    "destination": "GR",
    "size": "1GB",
    "package_type": "data-limited",
    "used_bytes": 858993459,
    "remaining_bytes": 214748365,
    "duration_days": 30,
    "elapsed_days": 24,
    "remaining_days": 6,
    "usage_percent": 80
  },
  "event_id": "package.usage.50_percent:pkg_xyz",
  "delivery_id": "dlv_2f1c8e9a-7b3d-4a52-9c10-1e6b2f0a4d77"
}

Responses

Webhook received successfully

package.usage.80_percentWebhook

Request

Triggered per package when 80% of the package's data has been consumed (data-limited) or 80% of the package's duration has elapsed (time-limited). This is the most effective trigger for top-up conversion.

Bodyapplication/json

eventstringrequired

Event type identifier

Example: "package.usage.80_percent"

timestampstring(date-time)required

dataobjectrequired

data.external_user_idstring

Partner's own user identifier

Example: "partner_user_456"

data.booking_idstring

Booking ID

Example: "booking_abc"

data.package_idstring

The specific package that triggered the event

Example: "pkg_xyz"

data.destinationstring

ISO country code

Example: "GR"

data.sizestring

Package size (data-limited packages only)

Example: "1GB"

data.package_typestring

Type of package

Enum"data-limited""time-limited""unlimited""starter"

Example: "data-limited"

data.used_bytesinteger

Bytes consumed so far (data-limited packages)

Example: 858993459

data.remaining_bytesinteger

Bytes remaining (data-limited packages)

Example: 214748365

data.duration_daysinteger

Total package validity in days (time-limited packages)

Example: 30

data.elapsed_daysinteger

Days elapsed since activation (time-limited packages)

Example: 24

data.remaining_daysinteger

Days remaining (time-limited packages)

Example: 6

data.usage_percentinteger

Usage percentage that triggered this event (50, 80, or 100). Represents data consumed (data-limited) or duration elapsed (time-limited).

Example: 80

event_idstringrequired

Example: "package.usage.80_percent:pkg_xyz"

delivery_idstringrequired

Identifier for this single delivery, also sent as the x-hubby-delivery-id header. A replay of the same event carries the same event_id but a new delivery_id.

Example: "dlv_2f1c8e9a-7b3d-4a52-9c10-1e6b2f0a4d77"

application/json

{
  "event": "package.usage.80_percent",
  "timestamp": "2019-08-24T14:15:22Z",
  "data": {
    "external_user_id": "partner_user_456",
    "booking_id": "booking_abc",
    "package_id": "pkg_xyz",
    "destination": "GR",
    "size": "1GB",
    "package_type": "data-limited",
    "used_bytes": 858993459,
    "remaining_bytes": 214748365,
    "duration_days": 30,
    "elapsed_days": 24,
    "remaining_days": 6,
    "usage_percent": 80
  },
  "event_id": "package.usage.80_percent:pkg_xyz",
  "delivery_id": "dlv_2f1c8e9a-7b3d-4a52-9c10-1e6b2f0a4d77"
}

Responses

Webhook received successfully

package.usage.100_percentWebhook

Request

Triggered per package when 100% of the package's data has been consumed (data-limited) or the full package duration has elapsed (time-limited).

Bodyapplication/json

eventstringrequired

Event type identifier

Example: "package.usage.100_percent"

timestampstring(date-time)required

dataobjectrequired

data.external_user_idstring

Partner's own user identifier

Example: "partner_user_456"

data.booking_idstring

Booking ID

Example: "booking_abc"

data.package_idstring

The specific package that triggered the event

Example: "pkg_xyz"

data.destinationstring

ISO country code

Example: "GR"

data.sizestring

Package size (data-limited packages only)

Example: "1GB"

data.package_typestring

Type of package

Enum"data-limited""time-limited""unlimited""starter"

Example: "data-limited"

data.used_bytesinteger

Bytes consumed so far (data-limited packages)

Example: 858993459

data.remaining_bytesinteger

Bytes remaining (data-limited packages)

Example: 214748365

data.duration_daysinteger

Total package validity in days (time-limited packages)

Example: 30

data.elapsed_daysinteger

Days elapsed since activation (time-limited packages)

Example: 24

data.remaining_daysinteger

Days remaining (time-limited packages)

Example: 6

data.usage_percentinteger

Usage percentage that triggered this event (50, 80, or 100). Represents data consumed (data-limited) or duration elapsed (time-limited).

Example: 80

event_idstringrequired

Example: "package.usage.100_percent:pkg_xyz"

delivery_idstringrequired

Identifier for this single delivery, also sent as the x-hubby-delivery-id header. A replay of the same event carries the same event_id but a new delivery_id.

Example: "dlv_2f1c8e9a-7b3d-4a52-9c10-1e6b2f0a4d77"

application/json

{
  "event": "package.usage.100_percent",
  "timestamp": "2019-08-24T14:15:22Z",
  "data": {
    "external_user_id": "partner_user_456",
    "booking_id": "booking_abc",
    "package_id": "pkg_xyz",
    "destination": "GR",
    "size": "1GB",
    "package_type": "data-limited",
    "used_bytes": 858993459,
    "remaining_bytes": 214748365,
    "duration_days": 30,
    "elapsed_days": 24,
    "remaining_days": 6,
    "usage_percent": 80
  },
  "event_id": "package.usage.100_percent:pkg_xyz",
  "delivery_id": "dlv_2f1c8e9a-7b3d-4a52-9c10-1e6b2f0a4d77"
}

Responses

Webhook received successfully

esim.installedWebhook

Request

Triggered when the traveler has successfully installed the eSIM on their device.

Bodyapplication/json

eventstringrequired

Event type identifier

Example: "esim.installed"

timestampstring(date-time)required

dataobjectrequired

Event-specific payload

data.external_user_idstring

Partner's own user identifier

Example: "partner_user_456"

data.booking_idstring

Booking ID

Example: "booking_abc"

data.iccidstring

ICCID of the eSIM

Example: "8901234567890123456"

event_idstringrequired

Example: "esim.installed:abc123"

delivery_idstringrequired

Identifier for this single delivery, also sent as the x-hubby-delivery-id header. A replay of the same event carries the same event_id but a new delivery_id.

Example: "dlv_2f1c8e9a-7b3d-4a52-9c10-1e6b2f0a4d77"

application/json

{
  "event": "esim.installed",
  "timestamp": "2019-08-24T14:15:22Z",
  "data": {
    "external_user_id": "partner_user_456",
    "booking_id": "booking_abc",
    "iccid": "8901234567890123456"
  },
  "event_id": "esim.installed:abc123",
  "delivery_id": "dlv_2f1c8e9a-7b3d-4a52-9c10-1e6b2f0a4d77"
}

Responses

Webhook received successfully

esim.removedWebhook

Request

Triggered when the traveler has removed the eSIM from their device. A removed eSIM can be re-installed — this event does not mean permanent loss of access.

Bodyapplication/json

eventstringrequired

Event type identifier

Example: "esim.removed"

timestampstring(date-time)required

dataobjectrequired

Event-specific payload

data.external_user_idstring

Partner's own user identifier

Example: "partner_user_456"

data.booking_idstring

Booking ID

Example: "booking_abc"

data.iccidstring

ICCID of the eSIM

Example: "8901234567890123456"

event_idstringrequired

Example: "esim.removed:abc123"

delivery_idstringrequired

Identifier for this single delivery, also sent as the x-hubby-delivery-id header. A replay of the same event carries the same event_id but a new delivery_id.

Example: "dlv_2f1c8e9a-7b3d-4a52-9c10-1e6b2f0a4d77"

application/json

{
  "event": "esim.removed",
  "timestamp": "2019-08-24T14:15:22Z",
  "data": {
    "external_user_id": "partner_user_456",
    "booking_id": "booking_abc",
    "iccid": "8901234567890123456"
  },
  "event_id": "esim.removed:abc123",
  "delivery_id": "dlv_2f1c8e9a-7b3d-4a52-9c10-1e6b2f0a4d77"
}

Responses

Webhook received successfully

package.activatedWebhook

Request

Triggered when a package has been activated and the traveler can use data. Typically occurs when the traveler arrives at the destination and connects to a local network.

Bodyapplication/json

eventstringrequired

Event type identifier

Example: "package.activated"

timestampstring(date-time)required

dataobjectrequired

Event-specific payload

data.external_user_idstring

Partner's own user identifier

Example: "partner_user_456"

data.booking_idstring

Booking ID

Example: "booking_abc"

data.package_idstring

Package ID

Example: "pkg_xyz"

data.destinationstring

ISO country code

Example: "GR"

data.sizestring

Package size

Example: "1GB"

data.activated_atstring(date-time)

When the package was activated

Example: "2026-07-15T16:00:00Z"

data.expires_atstring(date-time)

When the package expires

Example: "2027-07-15T16:00:00Z"

event_idstringrequired

Example: "package.activated:pkg_xyz"

delivery_idstringrequired

Identifier for this single delivery, also sent as the x-hubby-delivery-id header. A replay of the same event carries the same event_id but a new delivery_id.

Example: "dlv_2f1c8e9a-7b3d-4a52-9c10-1e6b2f0a4d77"

application/json

{
  "event": "package.activated",
  "timestamp": "2019-08-24T14:15:22Z",
  "data": {
    "external_user_id": "partner_user_456",
    "booking_id": "booking_abc",
    "package_id": "pkg_xyz",
    "destination": "GR",
    "size": "1GB",
    "activated_at": "2026-07-15T16:00:00Z",
    "expires_at": "2027-07-15T16:00:00Z"
  },
  "event_id": "package.activated:pkg_xyz",
  "delivery_id": "dlv_2f1c8e9a-7b3d-4a52-9c10-1e6b2f0a4d77"
}

Responses

Webhook received successfully

promo_code.redeemedWebhook

Request

Triggered when a traveler successfully redeems a promo code.

Bodyapplication/json

eventstringrequired

Event type identifier

Example: "promo_code.redeemed"

timestampstring(date-time)required

dataobjectrequired

Event-specific payload

data.promocodestring

The promo code that was redeemed

Example: "SUMMER2026GR"

data.booking_idstring

Booking ID

Example: "booking_abc"

data.redeemed_atstring(date-time)

When the promo code was redeemed

Example: "2026-07-10T12:00:00Z"

event_idstringrequired

Example: "promo_code.redeemed:SUMMER2026GR"

delivery_idstringrequired

Identifier for this single delivery, also sent as the x-hubby-delivery-id header. A replay of the same event carries the same event_id but a new delivery_id.

Example: "dlv_2f1c8e9a-7b3d-4a52-9c10-1e6b2f0a4d77"

application/json

{
  "event": "promo_code.redeemed",
  "timestamp": "2019-08-24T14:15:22Z",
  "data": {
    "promocode": "SUMMER2026GR",
    "booking_id": "booking_abc",
    "redeemed_at": "2026-07-10T12:00:00Z"
  },
  "event_id": "promo_code.redeemed:SUMMER2026GR",
  "delivery_id": "dlv_2f1c8e9a-7b3d-4a52-9c10-1e6b2f0a4d77"
}

Responses

Webhook received successfully

booking.within_cutoffWebhook

Request

Triggered when the booking's departure date enters the configured cutoff window (default: 7 days). This is the optimal time for travelers to install their eSIM while still at home on Wi-Fi. The esim_installed field indicates whether the traveler has already installed — use it to decide whether to send an installation reminder or a confirmation.

Bodyapplication/json

eventstringrequired

Event type identifier

Example: "booking.within_cutoff"

timestampstring(date-time)required

dataobjectrequired

Event-specific payload

data.external_user_idstring

Partner's own user identifier

Example: "partner_user_456"

data.booking_idstring

Booking ID

Example: "booking_abc"

data.departure_datestring(date-time)

ISO 8601 departure datetime with timezone

Example: "2026-07-15T14:30:00+02:00"

data.days_until_departureinteger

Days remaining until departure

Example: 7

data.esim_installedboolean

Whether the traveler has installed their eSIM

Example: false

event_idstringrequired

Example: "booking.within_cutoff:booking_abc"

delivery_idstringrequired

Identifier for this single delivery, also sent as the x-hubby-delivery-id header. A replay of the same event carries the same event_id but a new delivery_id.

Example: "dlv_2f1c8e9a-7b3d-4a52-9c10-1e6b2f0a4d77"

application/json

{
  "event": "booking.within_cutoff",
  "timestamp": "2019-08-24T14:15:22Z",
  "data": {
    "external_user_id": "partner_user_456",
    "booking_id": "booking_abc",
    "departure_date": "2026-07-15T14:30:00+02:00",
    "days_until_departure": 7,
    "esim_installed": false
  },
  "event_id": "booking.within_cutoff:booking_abc",
  "delivery_id": "dlv_2f1c8e9a-7b3d-4a52-9c10-1e6b2f0a4d77"
}

Responses

Webhook received successfully

booking.about_to_departWebhook

Request

Triggered when departure is imminent (default: 2 hours before the time in departure_date). This is the last-chance reminder for travelers who haven't installed their eSIM. Requires a full datetime with timezone in departure_date (e.g., 2026-07-15T14:30:00+02:00) — if only a date string was provided, this event cannot fire.

Bodyapplication/json

eventstringrequired

Event type identifier

Example: "booking.about_to_depart"

timestampstring(date-time)required

dataobjectrequired

Event-specific payload

data.external_user_idstring

Partner's own user identifier

Example: "partner_user_456"

data.booking_idstring

Booking ID

Example: "booking_abc"

data.departure_datestring(date-time)

ISO 8601 departure datetime with timezone

Example: "2026-07-15T14:30:00+02:00"

data.hours_until_departureinteger

Hours remaining until departure

Example: 2

data.esim_installedboolean

Whether the traveler has installed their eSIM

Example: false

event_idstringrequired

Example: "booking.about_to_depart:booking_abc"

delivery_idstringrequired

Identifier for this single delivery, also sent as the x-hubby-delivery-id header. A replay of the same event carries the same event_id but a new delivery_id.

Example: "dlv_2f1c8e9a-7b3d-4a52-9c10-1e6b2f0a4d77"

application/json

{
  "event": "booking.about_to_depart",
  "timestamp": "2019-08-24T14:15:22Z",
  "data": {
    "external_user_id": "partner_user_456",
    "booking_id": "booking_abc",
    "departure_date": "2026-07-15T14:30:00+02:00",
    "hours_until_departure": 2,
    "esim_installed": false
  },
  "event_id": "booking.about_to_depart:booking_abc",
  "delivery_id": "dlv_2f1c8e9a-7b3d-4a52-9c10-1e6b2f0a4d77"
}

Responses

Webhook received successfully

Hubby API (2.0.0)

Package Types

Webhook Delivery Authentication

Signature verification

Idempotency & event identity

Delivery, retries & replay

Booking

Package

Country

PromoCode

eSIM

WebView

Native API

Webhooks

package.usage.50_percentWebhook

RequestExpand all

Responses

Was this helpful?

package.usage.80_percentWebhook

RequestExpand all

Responses

Was this helpful?

package.usage.100_percentWebhook

RequestExpand all

Responses

Was this helpful?

esim.installedWebhook

RequestExpand all

Responses

Was this helpful?

esim.removedWebhook

RequestExpand all

Responses

Was this helpful?

package.activatedWebhook

RequestExpand all

Responses

Was this helpful?

promo_code.redeemedWebhook

RequestExpand all

Responses

Was this helpful?

booking.within_cutoffWebhook

RequestExpand all

Responses

Was this helpful?

booking.about_to_departWebhook

RequestExpand all

Responses

Was this helpful?

Request

Request

Request

Request

Request

Request

Request

Request

Request