How Wearable Data Flows From Device to Your API: A Complete Architecture Guide

Open Wearables Team · July 22, 2026 · 6 min read

Key Takeaways

Wearable data does not flow directly from device to your API. It goes through the provider's cloud first, then to Open Wearables via webhook or polling, then into your PostgreSQL instance, then out through the Open Wearables REST API.
The delivery model varies by provider: Garmin pushes data via webhook stream, Oura and Strava send webhook pings that trigger a follow-up pull, and mobile providers (Apple Health, Google Health Connect) send data through the device SDK.
Open Wearables uses Celery and Redis for background processing. Webhook events are processed asynchronously so your endpoint returns quickly even when data processing takes longer.
The normalized data model sits in PostgreSQL. Every provider's data lands in the same EventRecord, DataPointSeries, and PersonalRecord format before it reaches your application.
Your application never touches raw provider data. It queries the normalized Open Wearables REST API.

When developers first integrate wearable data, the mental model is simple: user has a device, device has data, data goes to your app. The actual flow has several more steps, and each step has implications for latency, reliability, and how you architect your application.

This article maps the full data flow from a user's wearable device to your application's API call, using Open Wearables as the integration layer.

The Full Data Flow

            Wearable Device
      |
      | (Bluetooth sync)
      v
Provider Cloud (Garmin Connect, Oura Cloud, Whoop, etc.)
      |
      | (webhook push or polling)
      v
Open Wearables Backend
      |
      | (Celery worker processes and normalizes)
      v
PostgreSQL (normalized data model)
      |
      | (REST API query)
      v
Your Application

Each step in this chain has different latency characteristics and failure modes.

Step 1: Device to Provider Cloud

The user wears the device. When the device syncs (via Bluetooth to the provider's mobile app, or via Wi-Fi in some cases), the raw sensor data uploads to the provider's cloud infrastructure.

This step happens entirely outside Open Wearables and outside your control. The sync frequency depends on the device and the provider. Most wearables sync automatically when the user opens the provider's app or when the device connects to the phone.

Step 2: Provider Cloud to Open Wearables

This is where provider architectures diverge significantly.

Webhook stream (Garmin): Garmin pushes the complete data payload directly to a registered endpoint on your Open Wearables instance. Open Wearables registers this webhook endpoint during the OAuth connection setup.
Webhook ping with REST pull (Oura, Strava, Polar, Whoop): The provider sends a lightweight notification to Open Wearables indicating that new data is available. Open Wearables receives the ping, then makes a REST API call to the provider to fetch the actual data. Oura, Strava, and Polar also support programmatic webhook registration through a provider API.
REST polling (Fitbit, Ultrahuman, and others): Open Wearables polls the provider's API on a schedule using Celery background tasks to check for new data.
Mobile SDK (Apple HealthKit, Google Health Connect, Samsung Health): There is no server-side API. The user's device runs the Open Wearables mobile SDK (Flutter for iOS, Android SDK for Google and Samsung), which reads data from the device and sends it to your Open Wearables instance directly.

Your Open Wearables instance exposes a webhook receiver endpoint for each supported provider. Webhook registrations are managed through the Open Wearables API:

            POST   /api/v1/webhooks/subscriptions
GET    /api/v1/webhooks/subscriptions
PUT    /api/v1/webhooks/subscriptions/{subscription_id}
DELETE /api/v1/webhooks/subscriptions/{subscription_id}

Step 3: Processing in Open Wearables

When data arrives (via webhook or polling), Open Wearables does not process it synchronously in the request handler. It queues the work for Celery background workers backed by Redis.

The webhook endpoint receives the payload and returns a 200 response quickly. The actual processing happens asynchronously: the Celery worker normalizes the data, maps it to the Open Wearables data model, handles deduplication, and writes to PostgreSQL.

You can also trigger manual syncs for a user and provider through the REST API:

            POST /api/v1/{provider}/users/{user_id}/sync
POST /api/v1/{provider}/users/{user_id}/sync/historical

Step 4: Normalized Storage in PostgreSQL

After processing, all provider data lands in the same normalized format regardless of its origin. The Open Wearables data model uses three primary types:

EventRecord (workouts, sleep sessions, menstrual cycle records): start and end timestamps, duration, activity type, aggregated values. Linked to EventRecordDetails for extended fields.
DataPointSeries (continuous time series): high or medium frequency sensor data (heart rate, SpO2, HRV, cadence). Each sample has a timestamp, type, value, unit, and source identifier.
PersonalRecord (user descriptors): slowly changing user information (birth date, sex, weight, height). Used to calibrate algorithms.

Every record carries a source identifier linking it to the provider and device that contributed it. This is how the priority system and deduplication work: the data is always stored per-source, and queries apply priority rules to determine what to return.

Step 5: Your Application Queries the REST API

Your application never interacts with raw provider data. It queries the normalized Open Wearables REST API using an API key generated in the developer portal.

            # Workouts for a user
GET /api/v1/users/{user_id}/events/workouts

# Sleep sessions
GET /api/v1/users/{user_id}/events/sleep

# Daily activity summary
GET /api/v1/users/{user_id}/summaries/activity

# Time series data
GET /api/v1/users/{user_id}/timeseries

All endpoints return data in the same format regardless of which provider the user has connected. Your application logic does not branch on provider.

What This Means for Your Application Architecture

Latency is not real-time. The chain from device to your API involves at least two hops before data reaches your system. Plan your application accordingly.
You do not need to be always-on for data delivery. Open Wearables stores data in your PostgreSQL instance as it arrives. Your application can query it on demand rather than needing to receive real-time events.
Outbound webhooks are on the roadmap. Check the GitHub repository for current implementation status. Until they are available, query the API on a schedule or use Celery tasks for scheduled processing.

FAQ

How quickly does data appear in my API after a user syncs their device?

It depends on the provider and delivery model. Garmin uses a webhook stream and data appears shortly after the user syncs. Providers that use webhook pings with REST pull (Oura, Strava, Polar) add a follow-up fetch step. Polling-based providers depend on the polling schedule. Mobile SDK providers (Apple Health) deliver data when the SDK sends it from the device.

Does Open Wearables handle webhook retries from providers?

Webhook endpoints return 200 responses quickly, which prevents providers from treating failed processing as a delivery failure. If the Celery worker encounters an error during processing, the task can be retried without the provider resending the original payload.

Can I trigger a manual sync for a user?

Yes. The API exposes sync endpoints per provider and user: POST /api/v1/{provider}/users/{user_id}/sync and POST /api/v1/{provider}/users/{user_id}/sync/historical. Historical sync availability depends on the provider.

What happens if Open Wearables is down when a provider sends a webhook?

The provider's webhook delivery fails. Provider retry behavior varies. For production deployments, ensure your Open Wearables instance has high availability. Data missed during downtime may need to be recovered through historical sync if the provider supports it.

Do I need to register webhook endpoints with each provider manually?

No. Open Wearables handles webhook registration with providers that support programmatic registration (Oura, Strava, Polar) through its webhook subscription API. For providers that require manual registration, the docs at docs.openwearables.io/provider-setup include setup guides.

Back to all posts