# HealthKit

- Tool: Bubble
- Difficulty: Intermediate
- Time required: 2–3 hours
- Last updated: July 2026

## TL;DR

HealthKit has no REST API — it is an on-device iOS framework with no cloud endpoint. The correct Bubble architecture is a two-stage bridge: an iOS Shortcut or native app reads HealthKit data and POSTs it to a Bubble Backend Workflow endpoint; Bubble then stores the payload and surfaces it in the UI. This requires a paid Bubble plan (Starter $32+/month) for Backend Workflows to function.

## Building a HealthKit-Powered Wellness App in Bubble

Founders building iOS wellness, fitness tracking, or corporate health apps frequently search for a Bubble HealthKit integration, expecting a REST API with an API key. The reality is different: HealthKit is Apple's on-device health data framework, and all data lives on the user's iPhone — there is no cloud endpoint, no API key to request, and no direct connection you can configure in Bubble's API Connector. Every tutorial that suggests adding an Apple endpoint to Bubble's API Connector is incorrect.

The architecture that actually works is a bridge pattern. An iOS Shortcut (free, no coding required, available on every iPhone running iOS 14+) or a custom-built native iOS app reads the user's HealthKit data — steps, heart rate, sleep, workout sessions, blood glucose — and sends it to your Bubble app using an HTTP POST request. Your Bubble app receives this data through a Backend Workflow (formerly called API Workflow), stores it in a custom HealthRecord Data Thing, and then displays it in your app's UI using standard Bubble elements and chart plugins.

This two-stage bridge gives you full control: you decide which health metrics to collect, how often to send them, and how to present them in Bubble. The iOS Shortcut approach requires no Apple Developer account to get started — users can download and run shortcuts on their own iPhones. A native Swift app gives you more control over background sync and data granularity, but requires a paid Apple Developer account ($99/year) and App Store submission.

The most important prerequisite: Backend Workflows in Bubble are only available on paid plans (Starter at $32/month or higher). If your Bubble app is on the free plan, the workflow endpoint that receives health data from iOS simply does not exist. Upgrade before you start building.

## Before you start

- A Bubble account on a paid plan (Starter at $32/month minimum) — Backend Workflows are not available on the free plan
- An iPhone running iOS 14 or later for testing the iOS Shortcut bridge (or an Apple Developer account for native app development)
- Basic familiarity with Bubble's Data tab, Workflow editor, and the concept of Backend Workflows
- Understanding that HealthKit data is per-user — each iPhone user's health data is separate, and your app must associate records with the correct Bubble user

## Step-by-step guide

### 1. Create the HealthRecord Data Type in Bubble

Before setting up any workflow, define where Bubble will store the incoming health data. In your Bubble editor, click the Data tab in the left sidebar, then click 'New type' and name it HealthRecord. Add the following fields: type (text — stores the health metric name, e.g., 'steps', 'heart_rate', 'sleep'), value (number — the numeric measurement value), unit (text — the unit of measurement, e.g., 'count', 'bpm', 'hours'), start_date (date — when the measurement period began), end_date (date — when it ended, same as start_date for instantaneous measurements), and user (type: User — links this record to a specific Bubble user for privacy filtering). This data model is flexible enough to store any type of health metric as a row. For a production app with many metric types, you might add more specific numeric fields (e.g., separate fields for steps_count, heart_rate_bpm, sleep_hours), but the generic type+value pattern works well to start. After creating the HealthRecord type, add a Privacy rule immediately: go to the Privacy sub-tab, click 'Define rules for HealthRecord', and set 'This HealthRecord is visible when: HealthRecord's user is Current User'. Health data is sensitive personal information — never leave this type publicly accessible.

**Expected result:** A HealthRecord Data Type exists in Bubble with type, value, unit, start_date, end_date, and user fields. A Privacy rule restricts visibility to the record's associated user.

### 2. Enable the Workflow API and create the receive_health_data Backend Workflow

Backend Workflows (also called API Workflows) are the mechanism that lets external services — in this case, iOS Shortcuts — POST data to your Bubble app over HTTP. You must explicitly enable this feature. Go to Settings (gear icon) → API tab → check the box labeled 'Enable Workflow API'. This creates a public endpoint namespace at https://YOUR-APP-NAME.bubbleapps.io/api/1.1/wf/. Important: this feature only appears and functions on paid Bubble plans. If you do not see the API tab checkbox, your plan does not include this feature — upgrade first.

Next, navigate to the Backend Workflows section (accessible from the main Workflow tab — look for 'Backend Workflows' in the tab bar). Click 'New API Workflow' and name it receive_health_data (no spaces — use underscores). In the workflow configuration, add the step 'Detect request data'. This is a special step that tells Bubble to listen for an incoming request and learn its JSON structure. You will need to send a real test POST to the workflow's initialize URL to teach Bubble the shape of your payload.

The endpoint URL for your workflow will be: https://YOUR-APP-NAME.bubbleapps.io/api/1.1/wf/receive_health_data. Keep this URL — you will configure the iOS Shortcut to POST to it. After Detect request data runs successfully once, all fields from the JSON payload become available in the rest of the workflow actions (Step 2: Create a new HealthRecord using the detected fields).

```
{
  "method": "POST",
  "url": "https://YOUR-APP-NAME.bubbleapps.io/api/1.1/wf/receive_health_data",
  "headers": {
    "Content-Type": "application/json",
    "X-Health-Sync-Key": "YOUR_SECRET_HEADER_VALUE"
  },
  "body": {
    "type": "steps",
    "value": 8432,
    "unit": "count",
    "start_date": "2026-07-09T00:00:00",
    "end_date": "2026-07-09T23:59:59",
    "user_email": "user@example.com"
  }
}
```

**Expected result:** The Workflow API is enabled. A Backend Workflow named 'receive_health_data' exists with a Detect request data step. The initialization URL is live and accessible.

### 3. Initialize the Backend Workflow with a real test payload

Bubble's Detect request data step requires receiving at least one real HTTP POST before Bubble knows what fields to expect. Without this initialization, the fields from the incoming payload are not available to subsequent workflow steps — you cannot reference request_data.type or request_data.value because Bubble has never seen them. This is the most common first-step blocker.

To initialize: open a terminal or use a tool like Postman (browser-based at app.getpostman.com) or the free Hoppscotch.io to send a POST request to the initialize URL, which is your workflow URL with /initialize appended: https://YOUR-APP-NAME.bubbleapps.io/api/1.1/wf/receive_health_data/initialize

Send a JSON body that matches the structure your iOS Shortcut will send. Use the sample payload shown in the code block above. Include all fields you intend to use — type, value, unit, start_date, end_date, and user_email (you will use user_email to look up the Bubble User record). The response from the initialize endpoint will be empty if successful. After sending the request, go back to your Backend Workflow in Bubble and open the action step after Detect request data — you should now be able to reference the detected fields like request_data's type, request_data's value, etc.

IMPORTANT: The initialize URL (/initialize suffix) is only for teaching Bubble the payload shape. The production iOS Shortcut must POST to the URL WITHOUT the /initialize suffix: https://YOUR-APP-NAME.bubbleapps.io/api/1.1/wf/receive_health_data. Sending live data to the initialize endpoint does not save records — it only updates Bubble's schema awareness.

```
# Send this with Postman or Hoppscotch to INITIALIZE (one-time setup only)
# POST to: https://YOUR-APP-NAME.bubbleapps.io/api/1.1/wf/receive_health_data/initialize

{
  "type": "steps",
  "value": 8432,
  "unit": "count",
  "start_date": "2026-07-09T00:00:00",
  "end_date": "2026-07-09T23:59:59",
  "user_email": "test@example.com"
}

# After initialization, the PRODUCTION endpoint (no /initialize) is:
# POST https://YOUR-APP-NAME.bubbleapps.io/api/1.1/wf/receive_health_data
```

**Expected result:** The Backend Workflow's Detect request data step has been initialized. The fields type, value, unit, start_date, end_date, and user_email are now available to reference in the Create a new HealthRecord action.

### 4. Add the Create HealthRecord action and protect data with Privacy rules

With the workflow initialized and Bubble aware of the incoming fields, add the data-saving action. In your receive_health_data Backend Workflow, after the Detect request data step, click the '+' to add a new step and choose 'Create a new thing'. Set the type to HealthRecord. Map the fields: type → request_data's type, value → request_data's value (as a number), unit → request_data's unit, start_date → request_data's start_date, end_date → request_data's end_date. For the user field, you cannot directly pass a Bubble User ID from iOS — instead, look up the user by email. Add a workflow step before Create that does a 'Do a search for' Users where email equals request_data's user_email and stores it in a workflow state. Then set HealthRecord's user to that search's first item.

After the Create step, you can optionally add a Return data from API action to send a JSON response back to iOS confirming success — return { 'status': 'ok', 'record_id': Result of step 2's unique id }.

Now verify your Privacy rules. Go to Data tab → Privacy tab → HealthRecord. Confirm the rule reads: 'This HealthRecord is visible when its user is Current User'. Click 'Find fields exposed to others' and ensure all fields are unchecked for 'Everyone else' — health data must never be publicly queryable. You should also consider adding a role-check if clinic admins need to view patient records: add a condition 'or Current User is an admin (App State or role field)'.

**Expected result:** The Backend Workflow creates a new HealthRecord for each incoming POST, maps all five health data fields, associates the record with the correct User by email lookup, and Privacy rules restrict record visibility to the associated user only.

### 5. Build the iOS Shortcut that reads HealthKit and POSTs to Bubble

The iOS Shortcuts app (pre-installed on every iPhone running iOS 14+) is the fastest way to bridge HealthKit to Bubble without writing Swift code. Open the Shortcuts app on an iPhone, tap the '+' button to create a new shortcut, and give it a name like 'Sync Health to [Your App Name]'.

Add these actions in order: (1) 'Find Health Samples' — configure it to find Steps samples for today (or a specific date range). For each health metric you want to sync, you will duplicate this action. (2) 'Get Details of Health Sample' — extract the Quantity value and Dates from each sample. (3) 'Get Contents of URL' — configure this as a POST request to your Bubble workflow URL (https://YOUR-APP-NAME.bubbleapps.io/api/1.1/wf/receive_health_data). Set the Request Body to JSON and build the body using the variables from the previous action: type = 'steps', value = the quantity number, unit = 'count', start_date = the start date formatted as ISO 8601, end_date = the end date formatted as ISO 8601, user_email = a Text action that returns the user's email. Add a Header for 'X-Health-Sync-Key' set to your secret value, and 'Content-Type' set to 'application/json'.

For multiple health metrics (steps + heart rate + sleep), repeat the Find Health Samples and POST steps for each metric. Add an 'Automation' trigger in the Shortcuts app to run this shortcut daily at a fixed time (e.g., 8 PM) so health data syncs automatically without the user tapping it manually. If you are building a native Swift app instead of using Shortcuts, RapidDev's team has built dozens of HealthKit bridge apps — reach out for a free scoping call at rapidevelopers.com/contact.

```
# iOS Shortcut Action: 'Get Contents of URL'
# Method: POST
# URL: https://YOUR-APP-NAME.bubbleapps.io/api/1.1/wf/receive_health_data
# Headers:
#   Content-Type: application/json
#   X-Health-Sync-Key: YOUR_SECRET_VALUE
# Body (JSON):
{
  "type": "steps",
  "value": [Shortcut Variable: Quantity from Health Sample],
  "unit": "count",
  "start_date": [Shortcut Variable: Start Date formatted as ISO 8601],
  "end_date": [Shortcut Variable: End Date formatted as ISO 8601],
  "user_email": "hardcoded-or-prompt-value@example.com"
}
```

**Expected result:** The iOS Shortcut reads today's step count (and any other metrics you configured), POSTs the data to your Bubble Backend Workflow, and the workflow creates a new HealthRecord in Bubble's database. You can verify this by checking the Logs tab in Bubble and searching the HealthRecord Data Type in the Data tab.

### 6. Build the Bubble UI: display health records in a dashboard

With data now flowing into Bubble's HealthRecord Data Type, build the display UI. Create a new page (e.g., 'health_dashboard') and add a Repeating Group element. Set the data source to 'Do a search for HealthRecords where user = Current User', with a date range filter using two Date Picker inputs for start and end dates.

For individual stats (today's total steps, this week's average sleep), use a Text element with an expression like 'Search for HealthRecords:sum of value' filtered to type = 'steps' and date = today. For trend charts, Bubble does not have a built-in chart element — install a chart plugin from the Plugins tab. Search for 'ApexCharts by Zeroqode' or 'Bubble Charts' and install it. Bind the chart's data series to a search for HealthRecords filtered by type = 'steps', ordered by start_date ascending, using the value field as the Y axis and start_date as the X axis.

For the sync instructions section, add a Text element that explains to users how to run the iOS Shortcut. Include a deep link button that opens the Shortcuts app: use a Link element with the URL 'shortcuts://'. Make the sync process discoverable — first-time users do not know they need to run a Shortcut.

For privacy on the page: wrap the Repeating Group in a condition that only shows data when the user is logged in ('only when Current User is logged in'). Add a login/signup popup for unauthenticated users.

**Expected result:** A Bubble dashboard page displays the current user's HealthKit-sourced step counts, and optionally heart rate or sleep metrics, filtered to their own records only. The chart plugin renders a trend line. The sync instructions are visible and actionable for first-time users.

## Best practices

- Protect HealthKit data with Bubble Privacy rules immediately — health data is sensitive personal information. Set HealthRecord visibility to 'only to its associated user' before going live, and use Bubble's 'Find fields exposed to others' tool to verify no fields are accidentally public.
- Add a secret header (X-Health-Sync-Key) to your Backend Workflow and validate it at the start of the workflow. Without authentication, anyone who discovers your workflow URL can POST arbitrary health data to your app.
- Use the /initialize endpoint once during setup to teach Bubble the incoming payload shape. Never confuse the /initialize URL with your production workflow URL — data sent to /initialize is not saved.
- Test the iOS Shortcut only on a real iPhone with real HealthKit data. HealthKit is unavailable in web browsers, Mac Safari, and Bubble's desktop preview canvas. Expect to do all iOS-side testing on device.
- Store one metric per HealthRecord row (one row for today's steps, a separate row for today's sleep). This makes filtering, sorting, and summing by metric type straightforward in Bubble's search expressions.
- Upgrade your Bubble plan before starting any implementation work. Backend Workflows require Starter ($32/month) or higher — the entire integration is blocked on the free plan.
- Inform users clearly in the app UI that they need to run an iOS Shortcut to sync their data. First-time users have no context for this requirement. Add an onboarding step that shows the Shortcut setup instructions.
- For chart display, install a chart plugin (ApexCharts by Zeroqode or similar) before designing the dashboard — Bubble has no native chart element. Factor plugin WU and plan compatibility into your tool selection.

## Use cases

### Build a personal fitness tracking dashboard

Let iPhone users connect their Apple Health data to a Bubble wellness app. An iOS Shortcut runs on a schedule (daily, after workouts) and POSTs steps, active energy, and sleep duration to a Bubble Backend Workflow. Bubble stores each entry as a HealthRecord and displays a dashboard with weekly step trends, sleep averages, and goal progress — all filtered to the current user's own data.

Prompt example:

```
Build a Bubble page showing a logged-in user's health stats: weekly steps chart (line chart, 7 days), average sleep hours this week, and today's active energy burn. Data comes from the HealthRecord Data Type filtered by Current User and date range. Add a 'Sync' button that shows instructions for running the iOS Shortcut.
```

### Corporate wellness program health data collection

For corporate wellness platforms, distribute an iOS Shortcut to enrolled employees. Each Shortcut includes a user token identifying the employee, which Bubble uses to associate incoming health data with the correct user record. Program administrators see an aggregated dashboard of participation rates and average activity metrics across the workforce.

Prompt example:

```
Build a Bubble admin page showing a Repeating Group of enrolled users with columns for last sync date, weekly average steps, and weekly average sleep hours. Pull from HealthRecord Data Type grouped by user. Add a participation rate indicator showing what percentage of enrolled users synced health data in the past 7 days.
```

### Healthcare provider patient activity monitoring

Clinics or physical therapy practices can monitor patient activity between appointments. Patients run an iOS Shortcut that sends daily step counts and workout sessions to the clinic's Bubble app. Providers see each patient's activity trend, spot low-activity days, and flag patients who may not be following prescribed exercise regimens.

Prompt example:

```
Build a Bubble patient portal page where a provider selects a patient from a dropdown and sees their daily step count for the past 30 days as a bar chart, average active minutes per week, and a list of their recent workout sessions. Data is from HealthRecord filtered by the selected User.
```

## Troubleshooting

### Backend Workflows section not visible or 'Enable Workflow API' checkbox missing in Settings → API

Cause: Bubble's Workflow API (Backend Workflows) is only available on paid plans. The free plan does not include this feature.

Solution: Upgrade your Bubble app to the Starter plan ($32/month) or higher. After upgrading, go to Settings → API and check 'Enable Workflow API'. The Backend Workflows section will then appear in the Workflow tab.

### The Backend Workflow runs but the Detect request data fields are empty — I cannot reference request_data's type or value in the Create action

Cause: Bubble's Detect request data step requires at least one successful real HTTP POST to the /initialize endpoint before it learns the payload shape. If you skipped this step, Bubble has no knowledge of the incoming fields.

Solution: Send a POST request to https://YOUR-APP-NAME.bubbleapps.io/api/1.1/wf/receive_health_data/initialize with your full sample JSON payload. Use Postman, Hoppscotch.io, or the Shortcuts app itself. After the initialization POST succeeds, go back to the Backend Workflow — the detected fields should now be selectable in the Create action dropdowns.

### Health data appears in the Bubble database but is not visible on the dashboard page

Cause: Privacy rules are filtering out records because the user field on HealthRecord does not match the logged-in user — often because the email lookup in the workflow returned no results, so the user field was saved as empty.

Solution: Go to the Data tab → HealthRecord and check if recent records have a populated user field. If user is empty, the email lookup in your Backend Workflow did not find a match. Verify that the user_email value sent by the iOS Shortcut matches the email address of the logged-in Bubble user exactly (case-sensitive). Add error handling in the workflow: 'Only when Do a search for Users:count > 0' before the Create step.

### iOS Shortcut returns an error or the Bubble workflow shows a failed request in Logs

Cause: The X-Health-Sync-Key header value does not match what is configured in the Bubble workflow condition, or the JSON body is malformed (e.g., date format incorrect, number field sent as string).

Solution: Check Bubble's Logs tab → Workflow logs to see the raw incoming request body and any error message. Verify the secret header value matches exactly (copy-paste, no trailing spaces). Ensure date values are formatted as ISO 8601 strings (YYYY-MM-DDTHH:MM:SS) and numeric values are sent as numbers, not quoted strings. In the iOS Shortcut, use the 'Format Date' action to ensure correct date format before building the JSON body.

## Frequently asked questions

### Can I connect Bubble directly to Apple HealthKit using the API Connector?

No. HealthKit is an on-device iOS framework with no REST API, no API key, and no cloud endpoint. You cannot add any Apple Health URL to Bubble's API Connector. The only way to get HealthKit data into Bubble is via a bridge: an iOS Shortcut or native app reads the data on the iPhone and POSTs it to a Bubble Backend Workflow.

### Does connecting HealthKit to Bubble require a paid Bubble plan?

Yes. The integration relies on Backend Workflows (formerly API Workflows) to receive inbound POSTs from iOS. Backend Workflows are only available on Bubble's paid plans (Starter at $32/month or higher). On the free plan, the Workflow API cannot be enabled and the endpoint does not exist.

### Do I need an Apple Developer account to build the iOS Shortcut bridge?

Not for the Shortcuts approach. The iOS Shortcuts app comes pre-installed on all iPhones running iOS 14+ and can access HealthKit data without an Apple Developer account. An Apple Developer account ($99/year) is only required if you want to publish a custom native iOS app to the App Store.

### How do I handle multiple users syncing their own HealthKit data?

Include the user's email address in the payload sent from the iOS Shortcut. In your Bubble Backend Workflow, search for a User record where email matches the incoming email, and set the user field on the created HealthRecord to that User. Add Privacy rules to HealthRecord so each user can only see their own records.

### Can I use this approach to sync data automatically without the user tapping anything?

Yes, using iOS Shortcuts Automation. In the Shortcuts app, open the Automation tab, tap the '+' button, and create a 'Time of Day' automation that runs your health sync shortcut daily at a fixed time (e.g., 9 PM). iOS may ask the user to confirm the first few runs — enable 'Run Immediately' in the automation settings to make it fully hands-free.

### What types of health data can I sync from HealthKit to Bubble?

Any data type that iOS Shortcuts can read via 'Find Health Samples': steps, heart rate, sleep analysis, active energy burned, workouts, blood glucose, blood pressure, body weight, oxygen saturation, respiratory rate, and more. Each metric type requires a separate 'Find Health Samples' action in your iOS Shortcut, and you send each as a separate POST (or bundle multiple metrics in one JSON body).

---

Source: https://www.rapidevelopers.com/bubble-integrations/healthkit
© RapidDev — https://www.rapidevelopers.com/bubble-integrations/healthkit