{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["tabs","tab"]},"type":"markdown"},"seo":{"title":"Hubby WebView","description":"Integrate Hubby eSIM into your travel platform with our comprehensive API documentation, tutorials, and guides.","keywords":"hubby, esim, api, travel, integration, documentation"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"hubby-webview"},"children":["Hubby WebView"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Hubby provides a fully managed web app that runs inside your mobile app's in-app browser. Your travelers claim packages, install their eSIM, monitor data usage, and buy top-ups — all within a branded experience you control. Your backend makes two API calls. Hubby handles everything else."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This page covers the complete flow: what you build, what Hubby handles, every API call in sequence, how authentication works, and what to do after you go live."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-you-build-vs.-what-hubby-handles"},"children":["What You Build vs. What Hubby Handles"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Your team"},"children":["Your team"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Hubby"},"children":["Hubby"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Backend calls to create bookings and redirect tokens"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Package provisioning, eSIM assignment, region optimization"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["WebView container in your app (open a URL)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Branded UI: claiming flow, installation instructions, data meter, top-up store"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Pass device info as query parameters when opening the WebView"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Device-tailored installation guides, localized UI"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Store ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_user_id"]}," per traveler"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Session management, token exchange, JWT lifecycle"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Map webhook events to push notifications (Phase 2)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Webhook event delivery, departure-time CRM triggers"]}]}]}]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Effort estimate:"]}," Backend: 3–5 days. Mobile: 2–3 days. No frontend build required — your app opens a URL."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"architecture"},"children":["Architecture"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Three actors are involved: your backend, the Hubby API, and the Hubby WebView running inside your app."]},{"$$mdtype":"Tag","name":"Mermaid","attributes":{"data-language":"mermaid","diagramSource":"sequenceDiagram\n participant PB as Partner Backend\n participant API as Hubby API\n participant WV as Hubby WebView
(in Partner App)\n\n PB->>API: POST /api/bookings\n API-->>PB: booking confirmation + package IDs\n\n PB->>API: POST /api/redirect-tokens/create\n API-->>PB: redirect_token (valid 5 min)\n\n PB->>WV: Open WebView with redirect_token\n\n WV->>API: POST /api/webapp/auth/exchange\n API-->>WV: session JWT\n\n WV->>API: GET /api/webapp/me/dashboard\n API-->>WV: user dashboard data\n\n WV->>WV: User claims packages,
installs eSIM, monitors data\n","diagramHtml":"
Hubby WebView(in Partner App)Hubby APIPartner BackendHubby WebView(in Partner App)Hubby APIPartner BackendPOST /api/bookingsbooking confirmation + package IDsPOST /api/redirect-tokens/createredirect_token (valid 5 min)Open WebView with redirect_tokenPOST /api/webapp/auth/exchangesession JWTGET /api/webapp/me/dashboarduser dashboard dataUser claims packages,installs eSIM, monitors data
"},"children":["sequenceDiagram\n participant PB as Partner Backend\n participant API as Hubby API\n participant WV as Hubby WebView
(in Partner App)\n\n PB->>API: POST /api/bookings\n API-->>PB: booking confirmation + package IDs\n\n PB->>API: POST /api/redirect-tokens/create\n API-->>PB: redirect_token (valid 5 min)\n\n PB->>WV: Open WebView with redirect_token\n\n WV->>API: POST /api/webapp/auth/exchange\n API-->>WV: session JWT\n\n WV->>API: GET /api/webapp/me/dashboard\n API-->>WV: user dashboard data\n\n WV->>WV: User claims packages,
installs eSIM, monitors data\n"]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-full-flow"},"children":["The Full Flow"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-1--create-a-booking"},"children":["Step 1 — Create a Booking"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/bookings"]}]}," — your backend calls this when a traveler qualifies for a package (e.g., at flight booking time, loyalty reward, or campaign trigger). The Booking entity maps directly to the travel booking you already have — a departure date, one or more destinations, and the bundles (data packages) for each."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"request-fields"},"children":["Request Fields"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["departure_date"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ISO 8601 datetime with timezone (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2026-07-15T14:30:00+02:00"]},"). Including the time and timezone enables precise CRM triggers such as push notifications 2 hours before departure"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["locale"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["WebView language (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["es"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fr"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["de"]},", etc.). See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/advanced-topics/supported-locales"},"children":["supported locales"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["custom_branding"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Selects your branded theme. Partners with multiple sub-brands pass the brand key here"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["package_specifications"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["array"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["One or more packages to provision"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"package-specification-fields"},"children":["Package Specification Fields"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_user_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Yes"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Required for WebView integration."]}," Your own identifier for the traveler receiving this package. This is the key that links the booking to the traveler across all subsequent calls — redirect tokens, WebView auth exchange, and sessions. Use your own internal user ID and pass the same value consistently."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["destination"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ISO 3166-1 alpha-2 country code (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GR"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["US"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["JP"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["size"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Data package size (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1GB"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["3GB"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5GB"]},")"]}]}]}]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Important:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_user_id"]}," is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["required"]}," for the WebView flow. It must be your own stable user identifier, and the same value must be used across all WebView endpoints — bookings, redirect tokens, and the auth exchange. If you are not using the WebView or ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/native-api"},"children":["Native eSIM Integration"]},", do not supply this field — it is ignored in the traditional booking flow and supplying it incorrectly will route the package into the eSIM management flow."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"multi-destination-bookings"},"children":["Multi-Destination Bookings"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A single booking can contain multiple entries in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["package_specifications"]},". Hubby automatically optimizes the assignment — for example, a trip covering Greenland, Canada, the US, and Mexico may be fulfilled with a single North America regional package plus individual packages where more cost-effective."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"example"},"children":["Example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl --request POST \\\n 'https://api.hubbyesim.com/api/bookings' \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'x-timestamp: 1717689600000' \\\n --header 'x-signature: YOUR_HMAC_SIGNATURE' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"departure_date\": \"2026-07-15T14:30:00+02:00\",\n \"locale\": \"es\",\n \"custom_branding\": \"your-brand\",\n \"package_specifications\": [\n {\n \"external_user_id\": \"partner_user_456\",\n \"destination\": \"GR\",\n \"size\": \"1GB\"\n }\n ]\n }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"success\": true,\n \"data\": {\n \"id\": \"booking_abc\",\n \"package_specifications\": [\n {\n \"external_user_id\": \"partner_user_456\",\n \"package_id\": \"pkg_xyz\",\n \"destination\": \"GR\",\n \"size\": \"1GB\",\n \"status\": \"provisioned\"\n }\n ]\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_user_id"]}," is required for the WebView flow. Always supply your own consistent user identifier — it is the key that ties the booking, redirect token, and WebView session together."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-2--create-a-redirect-token"},"children":["Step 2 — Create a Redirect Token"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/redirect-tokens/create"]}]}," — your backend calls this right before the traveler opens the eSIM section in your app. The response contains a short-lived ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirect_token"]}," that your app uses to open the Hubby WebView."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"request-fields-1"},"children":["Request Fields"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_user_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Your own user identifier"]}," — the same value you used in the booking's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["package_specifications"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirect_token"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["If you pre-generate the token, pass it here. Otherwise Hubby generates one"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"token-lifetime"},"children":["Token Lifetime"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The redirect token is valid for ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["5 minutes"]},". This prevents URL forwarding and sharing. If the token expires before the traveler opens the WebView, request a fresh one from the same endpoint."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Important:"]}," Do NOT cache the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirect_token"]},". Generate a new token every time the traveler opens the eSIM section in your app — on every open, on app resume if the WebView was killed by the OS, and if the 5-minute window expires."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"example-1"},"children":["Example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl --request POST \\\n 'https://api.hubbyesim.com/api/redirect-tokens/create' \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'x-timestamp: 1717689600000' \\\n --header 'x-signature: YOUR_HMAC_SIGNATURE' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"external_user_id\": \"partner_user_456\"\n }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"success\": true,\n \"data\": {\n \"redirect_token\": \"1b80dfe9-0202-4151-a26f-ceac52ca3b34\",\n \"expires_in\": 300\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-3--open-the-webview"},"children":["Step 3 — Open the WebView"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your app opens the Hubby WebView in an in-app browser using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirect_token"]}," returned in Step 2. Construct the URL as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://app.hubbyesim.com?t={redirect_token}"]}," and append device information as additional query parameters so the WebView can tailor eSIM installation instructions to the traveler's exact device."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"device-query-parameters"},"children":["Device Query Parameters"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["phone_os"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Operating system (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["iOS"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Android"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["phone_model"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Device model (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["iPhone 15 Pro"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Samsung Galaxy S24"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["os_version"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["OS version (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["17.4"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["14"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["phone_brand"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Device manufacturer (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Apple"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Samsung"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Google"]},")"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All parameters are optional. The WebView also performs its own browser-based device detection, but passing these values from the native app provides more accurate results — especially for device model and brand, which browsers cannot reliably detect."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"example-2"},"children":["Example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"https://app.hubbyesim.com?t=1b80dfe9-0202-4151-a26f-ceac52ca3b34&phone_os=iOS&phone_model=iPhone%2015%20Pro&os_version=17.4&phone_brand=Apple\n"},"children":[]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Tip:"]}," URL-encode parameter values. These parameters are read client-side by the WebView — they are never sent to the Hubby backend."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"what-the-traveler-sees"},"children":["What the Traveler Sees"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The WebView adapts to the traveler's state:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Traveler has unclaimed packages →"]}," A congratulations screen appears (\"You got 1GB for Greece!\"). The traveler can:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Accept"]}," — starts the eSIM installation flow, tailored to their exact device and OS version"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Skip"]}," — moves to the next unclaimed package"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After all packages are claimed (or skipped), the traveler sees the data meter."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["No unclaimed packages →"]}," The data meter screen shows:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Active package status and remaining data"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Option to buy more data"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If all packages have expired, a \"Get a package\" prompt"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"session-behaviour"},"children":["Session Behaviour"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Closing the WebView"]}," ends the session. The next time the traveler opens it, your app should generate a new redirect token (Step 2) and re-open."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Auth token persists"]}," across navigations within the same WebView session — no re-authentication while the browser instance is alive."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If the OS kills the WebView in the background, generate a new redirect token on app resume."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"esim-installation-url-handling"},"children":["eSIM Installation URL Handling"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the traveler taps \"Install eSIM\" inside the WebView, the web app navigates to a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["system-level provisioning URL"]},". These look like normal ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://"]}," links but are handled by the OS, not by a browser. A WebView will silently fail to load them unless your native app intercepts and hands them off to the OS."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["URLs the web app navigates to:"]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Platform"},"children":["Platform"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"URL"},"children":["URL"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Android"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://esimsetup.android.com/esim_qrcode_provisioning?carddata=LPA:1$$"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["iOS"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$$"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["carddata"]}," query parameter contains the GSMA LPA activation code in the format ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LPA:1$$"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Why this is needed:"]}," These URLs are not real websites. On Android, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["esimsetup.android.com"]}," is an ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developer.android.com/training/app-links"},"children":["Android App Link"]}," registered by the system eSIM provisioning service — it only works via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["startActivity"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACTION_VIEW"]},". On iOS, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["esimsetup.apple.com"]}," is handled by the iOS Cellular Setup service — it only works via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UIApplication.open(_:)"]},". If your WebView does not intercept these URLs, the navigation fails silently and the user sees nothing happen."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Your app must intercept these URL patterns and launch them externally:"]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"URL Pattern"},"children":["URL Pattern"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Platform"},"children":["Platform"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Action"},"children":["Action"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://esimsetup.android.com/*"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Android"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Launch with OS via Intent / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACTION_VIEW"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://esimsetup.apple.com/*"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["iOS"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Launch with OS via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UIApplication.open"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LPA:1$..."]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Both"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Launch externally (GSMA standard scheme)"]}]}]}]}]},{"$$mdtype":"Tag","name":"Tabs","attributes":{},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"label":"Android (Kotlin)"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Override ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shouldOverrideUrlLoading"]}," in your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WebViewClient"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","header":{"controls":{"copy":{}}},"source":"webView.webViewClient = object : WebViewClient() {\n override fun shouldOverrideUrlLoading(\n view: WebView,\n request: WebResourceRequest\n ): Boolean {\n val url = request.url.toString()\n\n // eSIM provisioning URL — launch with the OS\n if (url.startsWith(\"https://esimsetup.android.com/\")) {\n val intent = Intent(Intent.ACTION_VIEW, Uri.parse(url))\n startActivity(intent)\n return true\n }\n\n // Direct LPA activation code\n if (url.startsWith(\"LPA:\")) {\n val intent = Intent(Intent.ACTION_VIEW, Uri.parse(url))\n startActivity(intent)\n return true\n }\n\n return false\n }\n}\n","lang":"kotlin"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"iOS (Swift)"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Implement ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["decidePolicyFor"]}," in your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WKNavigationDelegate"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"func webView(\n _ webView: WKWebView,\n decidePolicyFor navigationAction: WKNavigationAction,\n decisionHandler: @escaping (WKNavigationActionPolicy) -> Void\n) {\n guard let url = navigationAction.request.url else {\n decisionHandler(.allow)\n return\n }\n\n let urlString = url.absoluteString\n\n // eSIM provisioning URL — launch with the OS\n if urlString.hasPrefix(\"https://esimsetup.apple.com/\") {\n UIApplication.shared.open(url, options: [:], completionHandler: nil)\n decisionHandler(.cancel)\n return\n }\n\n // Direct LPA activation code\n if urlString.hasPrefix(\"LPA:\") {\n UIApplication.shared.open(url, options: [:], completionHandler: nil)\n decisionHandler(.cancel)\n return\n }\n\n decisionHandler(.allow)\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add queried URL schemes to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Info.plist"]}," (optional but recommended):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"xml","header":{"controls":{"copy":{}}},"source":"LSApplicationQueriesSchemes\n\n LPA\n\n","lang":"xml"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"Flutter (Dart)"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webview_flutter"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["url_launcher"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"dart","header":{"controls":{"copy":{}}},"source":"_controller = WebViewController()\n ..setJavaScriptMode(JavaScriptMode.unrestricted)\n ..setNavigationDelegate(NavigationDelegate(\n onNavigationRequest: (NavigationRequest request) {\n final url = request.url;\n\n // eSIM provisioning URLs — launch with the OS\n if (url.startsWith('https://esimsetup.android.com/') ||\n url.startsWith('https://esimsetup.apple.com/')) {\n launchUrl(Uri.parse(url), mode: LaunchMode.externalApplication);\n return NavigationDecision.prevent;\n }\n\n // Direct LPA activation code\n if (url.startsWith('LPA:')) {\n launchUrl(Uri.parse(url), mode: LaunchMode.externalApplication);\n return NavigationDecision.prevent;\n }\n\n return NavigationDecision.navigate;\n },\n ))\n ..loadRequest(Uri.parse(webAppUrl));\n","lang":"dart"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"React Native"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["react-native-webview"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"tsx","header":{"controls":{"copy":{}}},"source":" {\n const { url } = request;\n\n // eSIM provisioning URLs — launch with the OS\n if (url.startsWith('https://esimsetup.android.com/') ||\n url.startsWith('https://esimsetup.apple.com/')) {\n Linking.openURL(url);\n return false;\n }\n\n // Direct LPA activation code\n if (url.startsWith('LPA:')) {\n Linking.openURL(url);\n return false;\n }\n\n return true;\n }}\n/>\n","lang":"tsx"},"children":[]}]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Testing:"]}," After implementing, create a booking and open the WebView. Tap \"Install eSIM\" — the device's native eSIM provisioning dialog should appear. If nothing happens, check your debug logs for the intercepted URL."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-4--token-exchange-automatic"},"children":["Step 4 — Token Exchange (automatic)"]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Partners do not call this endpoint. It is documented here for transparency and to help debug WebView network traffic."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the WebView loads with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirect_token"]},", it automatically calls:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/webapp/auth/exchange"]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"redirect_token\": \"1b80dfe9-0202-4151-a26f-ceac52ca3b34\",\n \"external_user_id\": \"partner_user_456\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This exchanges the short-lived redirect token for a session JWT. The JWT is scoped to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/webapp/"]}," endpoints only — it cannot be used for partner backend calls and your API keys are never exposed to the WebView."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-5--dashboard-load-automatic"},"children":["Step 5 — Dashboard Load (automatic)"]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Partners do not call this endpoint. Documented for transparency."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The WebView uses the session JWT to load the traveler's dashboard:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /api/webapp/me/dashboard"]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl --request GET \\\n 'https://api.hubbyesim.com/api/webapp/me/dashboard' \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The response includes active packages, data usage, unclaimed packages, and available actions. The WebView renders this into the branded UI."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-authentication-works"},"children":["How Authentication Works"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The WebView flow uses two separate auth contexts. They never mix."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"your-backend--hubby-api-hmac-sha256"},"children":["Your Backend → Hubby API (HMAC-SHA256)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All calls from your backend use HMAC-SHA256 signing. Every request includes:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-api-key"]}," — your public API key"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-timestamp"]}," — current Unix timestamp in milliseconds"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-signature"]}," — HMAC-SHA256 of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{timestamp}{METHOD}{path}"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This covers ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/bookings"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/redirect-tokens/create"]},", and all other partner-facing endpoints. See the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/authentication"},"children":["authentication guide"]}," for implementation details."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"webview--hubby-api-jwt"},"children":["WebView → Hubby API (JWT)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The WebView authenticates with a short-lived JWT obtained through the token exchange (Step 4). This is completely separate from your HMAC credentials — the WebView never has access to your API keys."]},{"$$mdtype":"Tag","name":"Mermaid","attributes":{"data-language":"mermaid","diagramSource":"sequenceDiagram\n participant PB as Partner Backend\n participant API as Hubby API\n participant WV as Hubby WebView\n\n Note over PB,API: HMAC-SHA256\n PB->>API: POST /api/redirect-tokens/create\n API-->>PB: redirect_token\n\n Note over WV,API: JWT\n WV->>API: POST /api/webapp/auth/exchange\n API-->>WV: session JWT\n WV->>API: GET /api/webapp/me/dashboard\n API-->>WV: dashboard data\n","diagramHtml":"
Hubby WebViewHubby APIPartner BackendHubby WebViewHubby APIPartner BackendHMAC-SHA256JWTPOST /api/redirect-tokens/createredirect_tokenPOST /api/webapp/auth/exchangesession JWTGET /api/webapp/me/dashboarddashboard data
"},"children":["sequenceDiagram\n participant PB as Partner Backend\n participant API as Hubby API\n participant WV as Hubby WebView\n\n Note over PB,API: HMAC-SHA256\n PB->>API: POST /api/redirect-tokens/create\n API-->>PB: redirect_token\n\n Note over WV,API: JWT\n WV->>API: POST /api/webapp/auth/exchange\n API-->>WV: session JWT\n WV->>API: GET /api/webapp/me/dashboard\n API-->>WV: dashboard data\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"security-properties"},"children":["Security Properties"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Time-limited tokens"]}," — the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirect_token"]}," expires in 5 minutes, preventing forwarding/sharing"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["No PII in the URL"]}," — the WebView URL contains only the opaque ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirect_token"]}," and optional device metadata"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Client-side device info"]}," — device parameters are read by the WebView client-side and never sent to the Hubby backend"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Scoped JWT"]}," — valid only for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/webapp/"]}," endpoints, tied to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_user_id"]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"identifier-reference"},"children":["Identifier Reference"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A single identifier — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_user_id"]}," — ties everything together across the WebView flow."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Endpoint"},"children":["Endpoint"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"How external_user_id is used"},"children":["How ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_user_id"]}," is used"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/bookings"]}," → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["package_specifications[]"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Links each package to a specific traveler"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/redirect-tokens/create"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ties the WebView session to the traveler"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/webapp/auth/exchange"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Validates the traveler matches the redirect token"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/webapp/refresh-esim"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Identifies which user to assign the fresh eSIM to"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use your own internal user ID as the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_user_id"]}," and pass the same value consistently across all three endpoints. This field is required for the WebView flow — the redirect token and auth exchange will fail without it."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"refresh-universal-esim"},"children":["Refresh Universal eSIM"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/webapp/refresh-esim"]}]}," — assigns a fresh universal eSIM to a user. If the user already has a universal eSIM, it is replaced. If they don't have one yet, a new eSIM is provisioned and assigned."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this to pre-provision an eSIM before the traveler opens the WebView, or to replace a problematic eSIM with a fresh one."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Authentication:"]}," Bearer JWT from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/webapp/auth/exchange"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"request-fields-2"},"children":["Request Fields"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_user_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your own user identifier — the same value used in bookings and redirect tokens"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"example-3"},"children":["Example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl --request POST \\\n 'https://api.hubbyesim.com/api/webapp/refresh-esim' \\\n --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIs...' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"external_user_id\": \"partner_user_456\"\n }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"success\": true,\n \"data\": {\n \"iccid\": \"8901234567890123456\",\n \"qr\": \"LPA:1$smdp.example.com$ACTIVATION-CODE\",\n \"status\": \"RELEASED\"\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]}," This endpoint is idempotent in intent — calling it always results in a fresh eSIM assigned to the user, whether or not they had one before. The previous eSIM (if any) is replaced."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-comes-next"},"children":["What Comes Next"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The WebView gets you live fast. Once it's running, you can progressively enhance the experience:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"communication--conversion-weeks-24"},"children":["Communication & Conversion (Weeks 2–4)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/advanced-topics/webhooks"},"children":["webhooks"]}," to receive real-time events and map them to push notifications:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["booking.within_cutoff"]}]}," — departure is 7 days away, send an installation reminder"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["booking.about_to_depart"]}]}," — 2 hours before flight (requires time + timezone in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["departure_date"]},"), last-chance install prompt"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["esim.installed"]}]}," / ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["esim.removed"]}]}," — track installation state"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["package.activated"]}]}," — traveler connected at destination"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["package.usage.20_percent"]}]}," / ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["package.usage.50_percent"]}]}," / ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["package.usage.80_percent"]}]}," — per-package usage milestones (data consumed or duration elapsed), drive top-up revenue at 80%"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"branding--segmentation"},"children":["Branding & Segmentation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/advanced-topics/branding"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["custom_branding"]}]}," to run separate branded themes per sub-brand. Different customer segments can receive different package sizes (e.g., premium members get 3GB, standard members get 1GB) by varying ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["size"]}," in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["package_specifications"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"zero-rated-traffic"},"children":["Zero-Rated Traffic"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ensure your core app functionality (boarding passes, booking management, payments) remains accessible to travelers even when their data package is depleted. Provide your critical IP ranges to Hubby and we configure zero-rated traffic policies."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"native-api-optional"},"children":["Native API (Optional)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For partners who want to go beyond the WebView, Hubby offers a Native API covering packages, provisioning, installation instructions, usage reporting, and event streams. The WebView and Native API coexist — many partners start with the WebView and selectively move high-traffic features (data meter, top-up) to native over time."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"troubleshooting"},"children":["Troubleshooting"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"token-expired-error-in-webview"},"children":["\"Token expired\" error in WebView"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The redirect token was not opened within 5 minutes. Generate a new token and re-open."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"invalid-external_user_id-error"},"children":["\"Invalid external_user_id\" error"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_user_id"]}," in the token exchange does not match the one used when creating the redirect token. Ensure your app passes the same identifier consistently."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"nothing-happens-when-traveler-taps-install-esim"},"children":["Nothing happens when traveler taps \"Install eSIM\""]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your WebView is loading the provisioning URL (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["esimsetup.android.com"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["esimsetup.apple.com"]},") as a webpage instead of launching it externally. Implement the URL interception described in ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#esim-installation-url-handling"},"children":["eSIM Installation URL Handling"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"webview-shows-a-blank-screen"},"children":["WebView shows a blank screen"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check your network inspector for a failed ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/webapp/auth/exchange"]}," call. Common causes:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Redirect token already consumed (tokens are single-use)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Network timeout during the exchange"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["WebView security settings blocking the request (ensure JavaScript is enabled and cross-origin requests are allowed for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["app.hubbyesim.com"]},")"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"quick-start-checklist"},"children":["Quick-Start Checklist"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["To go live, your team provides:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":false,"type":"checkbox","readOnly":true},"children":[]}," User identifier format (your internal user ID that becomes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_user_id"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":false,"type":"checkbox","readOnly":true},"children":[]}," Brand assets per sub-brand (logos, colors, copy)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":false,"type":"checkbox","readOnly":true},"children":[]}," Required locales for the WebView"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":false,"type":"checkbox","readOnly":true},"children":[]}," Customer segment → package size mapping"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":false,"type":"checkbox","readOnly":true},"children":[]}," Technical point of contact"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Hubby provides:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":false,"type":"checkbox","readOnly":true},"children":[]}," API keys (staging + production), per sub-brand if needed"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":false,"type":"checkbox","readOnly":true},"children":[]}," Branded WebView configured per sub-brand"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":false,"type":"checkbox","readOnly":true},"children":[]}," Staging environment with all endpoints"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":false,"type":"checkbox","readOnly":true},"children":[]}," Integration support"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related"},"children":["Related"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/v2_0_0/openapi"},"children":["API Reference — WebView endpoints"]}," — full OpenAPI spec for redirect tokens, token exchange, and dashboard"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/authentication"},"children":["Authentication guide"]}," — HMAC-SHA256 setup"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/advanced-topics/multi-destination"},"children":["Multi-destination bookings"]}," — advanced booking patterns"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/advanced-topics/branding"},"children":["Branding"]}," — configure branded themes"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/advanced-topics/webhooks"},"children":["Webhooks"]}," — real-time event delivery"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/advanced-topics/supported-locales"},"children":["Supported locales"]}," — available WebView languages"]}]}]},"headings":[{"value":"Hubby WebView","id":"hubby-webview","depth":1},{"value":"What You Build vs. What Hubby Handles","id":"what-you-build-vs.-what-hubby-handles","depth":2},{"value":"Architecture","id":"architecture","depth":2},{"value":"The Full Flow","id":"the-full-flow","depth":2},{"value":"Step 1 — Create a Booking","id":"step-1--create-a-booking","depth":3},{"value":"Request Fields","id":"request-fields","depth":4},{"value":"Package Specification Fields","id":"package-specification-fields","depth":4},{"value":"Multi-Destination Bookings","id":"multi-destination-bookings","depth":4},{"value":"Example","id":"example","depth":4},{"value":"Step 2 — Create a Redirect Token","id":"step-2--create-a-redirect-token","depth":3},{"value":"Request Fields","id":"request-fields-1","depth":4},{"value":"Token Lifetime","id":"token-lifetime","depth":4},{"value":"Example","id":"example-1","depth":4},{"value":"Step 3 — Open the WebView","id":"step-3--open-the-webview","depth":3},{"value":"Device Query Parameters","id":"device-query-parameters","depth":4},{"value":"Example","id":"example-2","depth":4},{"value":"What the Traveler Sees","id":"what-the-traveler-sees","depth":4},{"value":"Session Behaviour","id":"session-behaviour","depth":4},{"value":"eSIM Installation URL Handling","id":"esim-installation-url-handling","depth":4},{"value":"Step 4 — Token Exchange (automatic)","id":"step-4--token-exchange-automatic","depth":3},{"value":"Step 5 — Dashboard Load (automatic)","id":"step-5--dashboard-load-automatic","depth":3},{"value":"How Authentication Works","id":"how-authentication-works","depth":2},{"value":"Your Backend → Hubby API (HMAC-SHA256)","id":"your-backend--hubby-api-hmac-sha256","depth":3},{"value":"WebView → Hubby API (JWT)","id":"webview--hubby-api-jwt","depth":3},{"value":"Security Properties","id":"security-properties","depth":3},{"value":"Identifier Reference","id":"identifier-reference","depth":2},{"value":"Refresh Universal eSIM","id":"refresh-universal-esim","depth":2},{"value":"Request Fields","id":"request-fields-2","depth":4},{"value":"Example","id":"example-3","depth":4},{"value":"What Comes Next","id":"what-comes-next","depth":2},{"value":"Communication & Conversion (Weeks 2–4)","id":"communication--conversion-weeks-24","depth":3},{"value":"Branding & Segmentation","id":"branding--segmentation","depth":3},{"value":"Zero-Rated Traffic","id":"zero-rated-traffic","depth":3},{"value":"Native API (Optional)","id":"native-api-optional","depth":3},{"value":"Troubleshooting","id":"troubleshooting","depth":2},{"value":"\"Token expired\" error in WebView","id":"token-expired-error-in-webview","depth":3},{"value":"\"Invalid external_user_id\" error","id":"invalid-external_user_id-error","depth":3},{"value":"Nothing happens when traveler taps \"Install eSIM\"","id":"nothing-happens-when-traveler-taps-install-esim","depth":3},{"value":"WebView shows a blank screen","id":"webview-shows-a-blank-screen","depth":3},{"value":"Quick-Start Checklist","id":"quick-start-checklist","depth":2},{"value":"Related","id":"related","depth":2}],"frontmatter":{"title":"Hubby WebView","description":"How to embed the Hubby web app in your mobile app — from first booking to data meter, with the full API flow explained","seo":{"title":"Hubby WebView"}},"lastModified":"2026-04-26T18:00:55.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/webview","userData":{"isAuthenticated":false,"teams":["anonymous"]}}