Webhooks Guide

Hubby sends a webhook to your endpoint when something happens in a traveller's eSIM lifecycle: a booking is created, an eSIM is installed, a package activates or crosses a data threshold. Use the events to update your records, notify the traveller or start your own workflows.

This page has five parts:

1. Set-up: how an endpoint is created.
2. Verification: how you prove that a delivery comes from Hubby.
3. Delivery: answers, retries and deduplication.
4. Catalogue: every event, when it fires and which channels send it.
5. Bodies: the published contract, with the envelope, the headers and the body of every event.

Set-up

• Hubby creates the endpoint for you. Send your Hubby contact the URL and the events you want for each environment (staging and production). Events are chosen per endpoint, booking.created included.
• Hubby generates a 64-character signing secret for the endpoint. It is shown once, when the endpoint is created, and Hubby gives it to you. It cannot be read back later. Store it as a secret.
• Every endpoint that Hubby creates is signed.
• Optionally, Hubby can add a static header to every delivery, for example x-api-key or Authorization: Bearer …. You agree its name, value and prefix with Hubby. It is not your Partner API key, and it is not a verification mechanism.
• Optionally, Hubby can shape the body for your endpoint: a flat body (flat_payload) or a payload template per event (payload_templates). Both change the body shape. See Envelope in Bodies. An endpoint of a Partner on the Native channel (partner_app) always receives the default signed envelope: Hubby sets neither shaping for it, and does not create it without a secret.

Verification

Verify the signature on every delivery. Do not rely on the static header.

• x-hubby-timestamp: Unix time in seconds. Reject a delivery when it is too far from your clock (we recommend 5 minutes). This is your replay protection.
• x-hubby-signature: one sha256= value. Compute the lowercase hex HMAC-SHA256 of {x-hubby-timestamp}.{raw body} with your secret, and compare it in constant time. A verifier that splits the header on , and accepts any matching entry is also correct.

Use the raw request bytes as received. Do not parse and re-serialise the JSON first: a change in key order or whitespace breaks the match.

With the @hubbyesim/sdk package, verifyWebhook({ secret, body, headers }) does both checks and returns the parsed event. It throws WebhookVerificationError with a reason when a check fails.

A secret stays valid until Hubby regenerates it. A regeneration is a hard cutover: from the moment the new secret is stored, every delivery, retry and replay is signed with the new secret alone, and a delivery your verifier refuses with a 4xx is final. Switch your verifier the moment you receive the new secret; if you need time to switch, answer 5xx while you do, so that the delivery is retried. Each endpoint has its own secret.

Delivery

• Deduplicate on event_id. It is in the body and in the x-hubby-event-id header. It stays the same across retries and replays. delivery_id (also x-hubby-delivery-id) identifies one delivery; quote it when you contact support.
• Answer 2xx fast. The request times out after 10 seconds. Store the event and process it after you answer.
• A 4xx other than 429 is final. Hubby does not retry it. Use 4xx only for a request you will never accept.
• Everything else is retried: 5xx, 429, a timeout and a transport error. One delivery makes at most 12 attempts. The wait starts at 10 seconds and doubles up to 1 hour, about 3.4 hours in total.
• Do not answer 3xx. A redirect is followed, up to five times, and a 301, 302 or 303 becomes a GET without the body. The final answer's status is the one that counts.
• Order is not guaranteed. Treat each event as independent.
• On request, Hubby replays a delivery it already attempted to your endpoint. The replay has a new delivery_id, x-hubby-timestamp and signature; the event_id and the body, the envelope timestamp included, are the first send's. A delivery that was never attempted to your endpoint, for example from a time it was disabled or not subscribed, cannot be replayed.

Catalogue

The channel is how your travellers use Hubby: Native (your own app over the Partner API, see Native eSIM Integration), the Hubby app, or the Hubby web app (also when you show it in a WebView). An endpoint receives only the events it subscribes to, and only from the channels that can produce them.

booking.rescheduled is not sent as a webhook. A package that Hubby's support gives a traveller (an Operator grant) or ends for them (an Operator terminate) sends no event. The events in Legacy backend are not sent by the core Partner API.

Legacy backend

A Partner that still integrates with the legacy API receives its webhooks from the legacy backend. That backend also sends these events, which the core Partner API does not send:

• booking.within_cutoff and booking.about_to_depart: departure reminders.
• classic_package_queue.claimed: a classic-eSIM grant claimed in the Hubby app. The core name is package_queue.claimed.
• The package.usage.* events on elapsed duration for an unlimited package.

Bodies

The text below is Hubby's published webhook contract.

Partner Webhook Contract

What your webhook endpoint receives from Hubby: which events exist, how they are delivered and signed, and the fields of each body. There is no machine-readable schema for webhook events; this page is their description.

Every Partner receives the same bodies. Each event is described below as Hubby sends it today. If you integrated with Hubby's legacy webhooks, read If you used the legacy webhooks for what changed.

Events and channels

Which End-customer channel can produce each event. The channel is the surface your travellers use: native_app (the Hubby app), webapp (the Hubby web app, also when you show it in a WebView) and partner_app (your own app over the Partner API: Native (eSIM integration)). "All" means the event does not depend on the channel. An endpoint receives an event only when it subscribes to it; every event below, booking.created included, is chosen per endpoint.

On partner_app, your travellers buy nothing from Hubby and claim no code, so the five events in the last rows never reach you: your items carry no code and no upgrade link. For the same reason booking.created and booking.cancelled send you each package-queue item as {id} alone: the code and uuid keys other channels receive are absent (see Booking fields). A change of booking dates (booking.rescheduled) is not a webhook event: no endpoint can subscribe to it. A package that Hubby's support gives your traveller free of charge (an Operator grant) or ends for them (an Operator terminate) sends no event at all: not package_queue.claimed, not package.terminated, nothing.

Set-up

• Hubby creates the endpoint for you: the URL, the events it receives, and its optional shaping (see Envelope).
• Hubby generates a 64-character signing secret for every endpoint it creates, and gives it to you once, when the endpoint is created. It is stored encrypted and cannot be read back.
• On request, Hubby regenerates the secret. A secret change is a hard cutover: from the moment the new secret is stored, every delivery, every retry and every replay is signed with the new secret alone, and a delivery your verifier refuses with a 4xx is final. Switch your verifier the moment you receive the new secret. If you need time to switch, answer 5xx while you do, so that the delivery is retried.
• Every endpoint Hubby creates is signed. Only an endpoint carried over from the legacy webhook settings can lack a secret, and its deliveries then carry no x-hubby-signature.
• Hubby can also set a static header, for a receiver that wants one. It is optional. Its name (x-api-key when none is chosen), its value and an optional prefix are set per endpoint. It is not your API key, and it is not a verification mechanism: verify the signature.
• On request, Hubby sends a Test event to your endpoint: a real delivery of a sample body, marked as a test (see Headers and signature). A Test event differs from live traffic in four ways: its ids are fake TEST-… strings, its event_id is {event}:test-{random}, its envelope timestamp carries real milliseconds, and with a Flat body the test: true marker is a top-level key.

Delivery and retries

• Answer fast with a 2xx. The request times out after 10 seconds. Process the event after you answer.
• A 4xx other than 429 is final. The delivery is not retried.
• Anything else is retried: a 5xx, a 429, a timeout or a transport error. One delivery makes at most 12 attempts. The wait between attempts starts at 10 seconds and doubles to 1 hour (10 s, 20 s, 40 s, … 2560 s, 3600 s, 3600 s), about 3.4 hours in total.
• Do not answer 3xx. A redirect is followed, up to five times, and a 301, 302 or 303 is followed as a GET without the body. The status of the final answer is the one that counts.
• On request, Hubby replays a delivery it already attempted to your endpoint. The replay has a new delivery_id, x-hubby-timestamp and signature; event_id and the body, the envelope timestamp included, are the first send's.
• Every attempt is signed again with the time it is sent, so a 300-second timestamp tolerance holds for retries too.
• Deduplicate on event_id. A retry repeats event_id and delivery_id. Order is not guaranteed.

Envelope

{
  "event": "package.activated",
  "timestamp": "2026-07-15T16:00:00.123Z",
  "data": { "…": "the event body, below" },
  "event_id": "package.activated:01K…",
  "delivery_id": "01K…"
}

Two per-endpoint settings change this shape. Hubby sets both on request, and both run on the body described here, template first:

• payload_templates (a Payload template per event): the template is a map of output key to value. A value that is exactly {{name}} moves the field name out of data into the output key; any other value is a constant. Every field of data that no template value names is kept. The key order is fixed: the kept fields first, in their own order, then the template's keys in the template's order; a kept field that is also a template key stays in its original position and takes the template's value. A variable naming a field the event does not carry is null.
• flat_payload (a Flat body): the endpoint receives the data object alone (after its template, if any), with event_id and delivery_id appended to it. There is no event key and no timestamp key: tell the events apart by x-hubby-event-id, or by event_id, whose part before the first : is the event name.

An endpoint with neither receives the bodies below. An endpoint of a Partner on the partner_app channel always receives the bodies below, signed: Hubby does not set a flat body or a template for it, and does not create it without a secret.

Headers and signature

Every delivery is a POST with Content-Type: application/json.

To verify: read x-hubby-timestamp and the raw request body exactly as received, compute sha256= + hex HMAC-SHA256 of {timestamp}.{body} with the secret, and compare it, in constant time, with x-hubby-signature. Hubby sends one signature per delivery; a verifier that splits the header on , and accepts any matching entry is also correct.

Verify the signature over the bytes received, not over a re-serialised body: the order of keys inside data is not guaranteed. (A Payload template fixes the order of its own output.)

Conventions

For the package and eSIM events (package.activated, topup.completed, package.purchased, package.usage.*, package.first_usage, esim.installed, esim.removed, esim.location_change; the first two points also hold for booking.created):

• A field Hubby cannot resolve is an explicit null, never absent.
• Fields that a table marks Additional, and fields that no table lists, may appear. Ignore keys you do not read.
• size is the whole number of GiB, rounded: round(bytes / 2^30) + "GB" (1.5 GiB → "2GB", 1.49 GiB → "1GB", 500 MiB → "0GB"). For an unlimited Package it is the fair-use ceiling, not the size sold; duration_days is the field that tells unlimited Packages apart.
• package_type is data-limited, starter or unlimited on these events. The other events send data_limited. The deprecated time-limited is never sent, on any event.
• expires_at is the provider's activation deadline: the last moment the Package can start. It is the same value the Partner API returns as expires_at. It is not activation plus the time allowance.
• destination is the Package's destination code: ISO 3166-1 alpha-3, uppercase, for a country (NLD); the region code for a region or global destination (EU, XCA), as the legacy webhooks sent it. It is the same value the Partner API's legacy routes publish as the destination id.

For every event:

• booking_id is your booking reference (external_reference on /api/v1), or null when there is none. No event sends Hubby's own booking id under that name. Each event's table says which booking it names.
• "The booking the eSIM was claimed with" is the booking of the package-queue item behind the eSIM's first Package, when that item was your grant (from a booking or a promo code) and not a purchase, a Switch or an Operator grant. "The code the eSIM was claimed with" is that item's code.
• package_queue_uuid and queue_id both carry a package-queue item's id: items[].id on /api/v1. It is the value to correlate on and is NOT the key of that item's upgrade-offer page. See Two identifiers per package-queue item. One exception: for an item migrated from the legacy platform, package_queue_uuid is the item's id on the legacy platform, which is the id you received for it there. queue_id and items[].id stay Hubby's id for the same item.
• package_id is an opaque id. Do not parse it.
• An id is the same string in a webhook and on /api/v1, in the same letter case. Most ids are lowercase ULIDs, but some are uppercase: for example the id of an eSIM from Hubby's stock, or of a booking item that Hubby imported. Compare and look up ids exactly as you received them: do not change their case.

package.activated

The provider activated the Package and reported it to Hubby. The event is sent when the provider activates the Package; Hubby does not observe the network attach itself.

package.terminated

You ended a Package you issued over the Partner API (DELETE /v1/bookings/{booking}/items/{item}/package), before Package activation. The Package is ended on the network, nothing is charged, and the booking item is queued again: it can be issued again or its booking cancelled. The traveller keeps their eSIM. event_id entity: the Package, so a later issue and terminate of the same item is a new event. Sent once per terminate; a refused terminate sends nothing. A terminate done by Hubby, or an end by the network provider, is not sent.

The body uses the Partner API's names, except booking_id, which means what it means on every other event.

topup.completed

A paid top-up was provisioned onto an eSIM. It is sent once the Package exists, not when the payment settles.

payment_id

payment_id is Hubby's own payment record, because it is never null: a sale settled through a Checkout Session has no intent id. To key on the Stripe id, read payment_intent_id.

package.purchased

A paid purchase was provisioned onto an eSIM: the traveller's universal eSIM, or one claimed for them if they had none. It is sent once the Package exists, when the traveller redeems the purchase, not when the payment settles.

package.usage.50_percent, package.usage.80_percent, package.usage.100_percent

The connectivity provider sent a data-percentage alert for a Package, and the percentage it reported falls in a window: above 47 and below 55 percent (50_percent), above 75 and below 85 percent (80_percent), or above 90 percent (100_percent). An alert outside every window sends nothing. Each fires at most once per Package. event_id entity: the Package.

The provider's alert is the only trigger. For an unlimited Package the percentage is of the fair-use cap (the size it carries). Nothing fires on elapsed time: a Package that runs out of days sends no usage event.

package.first_usage

A Package's used data reaches 10 MB (10 × 1024 × 1024 bytes). Hubby reads usage from the provider every 15 minutes, so the event can arrive up to about 15 minutes late; first_used_at is when Hubby observed it. Fires once per Package. event_id entity: the Package. The fields it shares with package.activated have the same meanings.

esim.installed, esim.removed

esim.installed: the provider reported the eSIM profile installed on a device, enabled or not, for the first time. Fires once per eSIM.

esim.removed: the provider reported that an installed eSIM was deleted from its device. Fires once per eSIM, like esim.installed: a second removal of the same eSIM is not sent.

event_id entity: the eSIM, for both.

An eSIM outlives its bookings, so booking_id here is your reference of the booking the eSIM was first claimed with, not the booking of a later Package on it. To tie the event to a booking item, correlate on queue_id (the item's id, items[].id on /api/v1) and package_id.

esim.location_change

Triggered when one of your travelers' eSIMs attaches to a mobile network in a different country than it was last seen in — detected from the network operator's hourly location-update feed, which Hubby reads every 15 minutes, so expect 15 to 75 minutes of latency, more when a delivery is retried, and occasional out-of-order delivery (order by at). from_country: null means this is the first attach ever observed for the ICCID. Deduplicate on event_id.

It is sent only for an eSIM that has a traveller. A change read more than 24 hours after at is not sent.

event_id entity: the provider's location update, so event_id reads esim.location_change:{update id}.

payment.refunded

Stripe reported a refund on a payment made with Hubby. One event per Stripe refund, so a second partial refund is a second event. It is sent also when the refunded sale was never redeemed; package_id is then null.

booking.created

A booking was created, including by a bulk import. event_id entity: the booking, so an endpoint receives one delivery per booking, however many travellers it names.

The body is the fields below, then the Booking fields:

booking.cancelled

You cancelled a booking through the booking API (DELETE /v1/bookings/{id}, or the legacy DELETE /bookings/{id} and DELETE /bookings/{id}/byExternalBookingId): its trip contact was anonymised and every package still queued on it was cancelled, so none of its codes can be redeemed any more. event_id entity: the booking, so an endpoint receives one delivery per booking. Sent once: cancelling a booking that is already cancelled succeeds and sends nothing, and a refused cancellation sends nothing.

The body is booking.created's, field for field, read from the booking after the cancellation, so one parser reads both:

• status is CANCELLED, and booking.cancelled_at is when the booking was cancelled.
• No field carries the trip contact: the cancellation is recorded after the anonymisation, and no booking event ever carries it.
• first_package_queue_item and package_queue_items still name the traveller's items, and on native_app and webapp their codes, so an endpoint can match them to what booking.created sent; those codes no longer redeem. On partner_app each item is {id}, as on booking.created.

The other events

These events use their own field names, apart from booking_id, which is your booking reference on each of them (see Conventions). The Conventions for size and package_type do not apply here: these events send size as a label ("3GB", "1.50GB", "500MB", "0 Bytes", binary units) and package_type as data_limited, starter or unlimited.

Rules that hold for all of them:

• Ids are 26-character ULIDs unless the table says otherwise. Their letter case follows the rule for every event above.
• destination is the Package's destination code: ISO 3166-1 alpha-3, uppercase, for a country (NLD); for a region or global destination the region code the legacy webhooks sent (EU, XCA). null only when the Package has no destination.
• Timestamps inside data are ISO 8601 UTC with six fractional digits. A timestamp read from a stored date ends in .000000Z; redeemed_at carries real microseconds. The envelope timestamp is different: it has milliseconds on every event (see Envelope).
• external_user_id is the traveller's id in your own system. It is the one key that can be absent rather than null: it is left out when the event has no customer. Only upgrade_offer.purchased can reach you without one.

Package fields

Sent by package_queue.claimed.

Booking fields

Sent by booking.created and booking.cancelled, after their own fields. Their own destinations is an array of strings (see booking.created); the objects for the same destinations are in destination_details.

The three package_queue keys are absent, not null, for a traveller with no package-queue item on the booking.

Neither of the item's two ready-made links (upgrade_url, deep_link_url) is sent on this or any other event — they are booking API fields, described in The two links on a booking item. On native_app and webapp this event carries the uuid one of them is composed from, so an endpoint that wants the upgrade link without a second call can build it; the deep link needs the code, which this event also carries. On partner_app your travellers have neither a code to type nor an upgrade page to open, so the two bearer values are not sent: each item is {id}.

A booking event's event_id is the booking's, so an endpoint receives one delivery of each booking event per booking. When a booking has several travellers, that delivery describes the first traveller recorded; the others are not delivered.

Two identifiers per package-queue item

A package-queue item carries two identifiers that are both called some form of "uuid" somewhere in Hubby's APIs. They are different values and are never interchangeable:

Two consequences:

• package_queue_uuid is the id, despite the name. It does not carry the offer key, on any event. The name is kept from the legacy webhooks. For an item migrated from the legacy platform it is the item's legacy id, not items[].id (see Conventions).
• promo_codes[].uuid on the booking API is the id, not the offer key. To build an upgrade link, read offer_uuid, or simply send the upgrade_url the booking API returns ready-made.

The offer link itself is {public-pages base URL}/offer/{offer key}. You do not need to know that shape: every booking API response that carries an item carries upgrade_url beside offer_uuid, already composed, except on partner_app, where both are absent. The link is a bearer capability URL — whoever opens it can buy an upgrade for that package — so it belongs only in the traveller's hands, never anywhere public.

The two links on a booking item

The booking API returns two ready-made links per item. Neither is sent on any webhook event; both are read off a booking response.

Both are meant to be used as given, not rebuilt. Their base URLs are deployment configuration and can move without notice; the fields cannot.

promo_code.redeemed

A traveller claimed a code. event_id entity: the package-queue item, so each redemption of a multi-use code is its own event. It goes to the claimant's Partner.

package_queue.claimed

A traveller redeemed your grant, or you issued it over the Partner API, and its Package was provisioned. The grant is a package-queue item from a booking, or one redeemed through a promo code. Sent once per item: a re-issue after a terminate carries the same event_id, so it is not delivered again. A promo code with no booking fires it too, with booking_id null. A purchase, a paid top-up, a Switch or an Operator grant does not fire it. event_id entity: the package-queue item. activated_at is usually null at this point; expires_at is set. Body: Package fields and:

upgrade_offer.purchased

An upgrade offer was paid, either as an upgrade of an existing package-queue item or as a top-up. event_id entity: the upgraded item, or the top-up's new item. It is sent when the payment settles: an upgrade provisions nothing, so it has no Package to wait for. The Package description is what was sold, not what was provisioned; for an upgrade, the Package description, booking_id and promo_code describe the item before the upgrade.

If you used the legacy webhooks

The envelope, the headers and the signature scheme are the legacy webhooks', so your verification keeps working with the secret you already hold. The event names and the bodies differ as below.

Names

The other classic_* events are not sent.

Values that differ

• booking_id is always your booking reference, or null. On the legacy webhooks it could be a Hubby document id or a Checkout Session id.
• Fields marked Additional were not on the legacy webhooks. Ignore the keys you do not read.
• Envelope timestamp is the moment the event occurred, not the moment it was queued. event_id and delivery_id ids have a new form; they never collide with legacy ids.
• Static header prefix: one space is put between the prefix and the value. A prefix stored as "Bearer" arrives as Bearer key, not Bearerkey.
• Key order inside data can differ. Verify over the bytes received.
• package.activated and package.usage.*: booking_id is the booking that bought the Package (the booking of its own item). The legacy value was the promo's booking, or else the booking of the Package's own item; the two differ when the promo's booking is not the Package's own.
• package.usage.*: fired only by the provider's data alert, never on elapsed time, and the 50 percent event fires on its own window, whatever the template. The byte counts are from the alert that fires the event, or from the last stored reading when the alert carries none. remaining_bytes is null, not 0, when the total is unknown. elapsed_days counts calendar days, not whole 24-hour periods. remaining_days counts calendar days to the end of the validity; the legacy value was duration_days − elapsed_days in 24-hour periods, so the two can differ by one day.
• esim.installed is sent when the provider reports the profile installed on a device, enabled or not; not when the profile starts to download.
• esim.location_change is sent only for an eSIM that has a traveller, and not when the change is read more than 24 hours late. event_id is the same value as on the legacy webhooks for the same update.
• topup.completed: payment_id is always Hubby's payment record; the Stripe id is always on payment_intent_id. The event is sent when the Package exists, not at payment.
• package.purchased: sent when the purchase is redeemed, always with the iccid of the eSIM the Package went onto and the package_queue_uuid.
• payment.refunded: refund_type is full as soon as the refunded total reaches the charge; amount is divided by the currency's own factor, not always by 100; the event is sent even when no eSIM is found for the payment.
• booking.created: destination values follow the Conventions rule (ISO 3166-1 alpha-3 for a country, the region code for a region), and size is rebuilt from bytes ("1024MB" comes back as "1GB", and 1.5 GiB as "1536MB").
• promo_code.redeemed: every redemption of a multi-use code is sent, not only the first.
• promo_codes[].uuid on the booking API's legacy routes is the item's id. On the legacy API it was the offer key; read offer_uuid instead.
• deep_link_url on booking responses is the same link as on the legacy API, with the same shape.