Receive real-time notifications when health data arrives for your users. Register HTTPS endpoints, filter by event type or user, verify signatures, and debug delivery.
Outgoing webhooks let Open Wearables push events to your backend in real time, so you don’t need to poll for new data. Each time a workout is saved, sleep is recorded, or a timeseries batch is ingested, Open Wearables fires an HTTP POST request to every registered endpoint that matches the event.Webhooks are delivered via Svix, which handles retries, signature signing, and delivery history.
Things you can do
Trigger downstream processing when a workout is synced, update your UI in real time when sleep data arrives, scope an endpoint to a single user’s events, or verify payloads are genuinely from Open Wearables.
Requirements
A developer account and a Bearer token (from POST /api/v1/auth/login), plus a publicly reachable HTTPS URL for your endpoint.
Store this secret securely on your server — you’ll use it to verify every incoming request.
3
Handle incoming events
Open Wearables sends a POST to your URL with a JSON body and three signature headers. Verify the signature before processing.
Python
Node.js
cURL (manual verify)
from svix.webhooks import Webhook, WebhookVerificationErrorfrom fastapi import FastAPI, Request, HTTPExceptionapp = FastAPI()WEBHOOK_SECRET = "whsec_C2FVsBQIhrscChlQIMV+b5ND9vAIBZaM7ZqtLnNYGDA="@app.post("/webhooks/health")async def handle_webhook(request: Request): headers = dict(request.headers) payload = await request.body() try: wh = Webhook(WEBHOOK_SECRET) event = wh.verify(payload, headers) except WebhookVerificationError: raise HTTPException(status_code=400, detail="Invalid signature") event_type = event["type"] if event_type == "workout.created": data = event["data"] print(f"New workout for user {data['user_id']}: " f"{data['type']} — {data['duration_seconds']}s") elif event_type == "sleep.created": data = event["data"] print(f"New sleep for user {data['user_id']}: " f"efficiency {data.get('efficiency_percent')}%") return {"ok": True}
import { Webhook } from "svix";import express from "express";const app = express();const WEBHOOK_SECRET = "whsec_C2FVsBQIhrscChlQIMV+b5ND9vAIBZaM7ZqtLnNYGDA=";app.post( "/webhooks/health", express.raw({ type: "application/json" }), (req, res) => { const wh = new Webhook(WEBHOOK_SECRET); let event; try { event = wh.verify(req.body, req.headers); } catch (err) { return res.status(400).json({ error: "Invalid signature" }); } if (event.type === "workout.created") { console.log(`Workout for user ${event.data.user_id}:`, event.data.type, event.data.duration_seconds + "s"); } res.json({ ok: true }); });
# The three signature headers sent with every request:# svix-id — unique message ID (for idempotency)# svix-timestamp — Unix timestamp of delivery attempt# svix-signature — comma-separated list of v1,<base64_hmac> signatures## To verify manually:# 1. Build the signed content: "{svix-id}.{svix-timestamp}.{raw_body}"# 2. HMAC-SHA256 the content with the base64-decoded key (strip "whsec_" prefix)# 3. Base64-encode the result# 4. Compare with the signature in the svix-signature header
Install the Svix library: pip install svix / npm install svix. The Webhook.verify() call handles timestamp tolerance (rejects messages older than 5 minutes) and all signature edge cases automatically.
4
Send a test event
Trigger a realistic example payload to your endpoint to confirm end-to-end delivery before you go live.
Fired once when a complete session is saved or merged.
Event
Description
connection.created
A user successfully connected a wearable provider.
connection.revoked
A connection became invalid (refresh token expired/revoked, or the user deregistered on the provider side). The user must re-authorize to resume syncing.
Fired per ingestion batch — one event per distinct (user, provider, series_type) combination in a sync run. Each event carries the full samples array, so consumers can store data directly from the webhook without issuing follow-up API calls.
pregnancy_snapshot is populated (as a list with one entry) when the user is tracking a pregnancy. Garmin reuses the same summary ID for daily cycle updates — Open Wearables deduplicates by external_id, so the event fires only when a new record is first inserted.
Each entry in samples matches the schema returned by GET /api/v1/users/{user_id}/timeseries, so consumers work with a single schema regardless of whether data comes from a webhook or the pull API.
is_daily_total distinguishes pre-aggregated daily totals from intraday samples for additive series (steps, energy, distance, flights):
Value
Meaning
true
Pre-aggregated daily total reported by the device. Use this value directly — do not add intraday samples from the same day and source on top of it.
false
Intraday sample (e.g. a 15-minute epoch). Sum these when no daily total is present.
null
Legacy row ingested before this field was introduced, or a series type where daily vs. intraday does not apply (e.g. heart rate). Treat the same as false.
For non-additive series (heart rate, SpO2, temperature, …) is_daily_total is always null and can be ignored.
Large batches (exceeding 2 500 samples) are automatically split into consecutive chunk events to stay within Svix’s 1 MB payload limit. Each chunk event includes chunk_index (0-based) and total_chunks so you can detect and reassemble split deliveries. The sample_count field always reflects the total number of samples across all chunks.
The pull API (GET /api/v1/users/{user_id}/timeseries) remains available for backfill, reconciliation, or recovery after missed deliveries.
from svix.webhooks import Webhook, WebhookVerificationErrorwh = Webhook("whsec_YOUR_SIGNING_SECRET")try: # headers must include svix-id, svix-timestamp, svix-signature payload = wh.verify(raw_body_bytes, headers_dict)except WebhookVerificationError: # reject — signature invalid or timestamp too old return 400
Install: pip install svix
import { Webhook } from "svix";const wh = new Webhook("whsec_YOUR_SIGNING_SECRET");try { const payload = wh.verify(rawBodyBuffer, headersObject);} catch (err) { // reject — signature invalid or timestamp too old return res.status(400).end();}
Install: npm install svix
# 1. Decode the key: base64_decode(key.removePrefix("whsec_"))# 2. Build the signed string: "{svix-id}.{svix-timestamp}.{raw_body}"# 3. Compute: HMAC-SHA256(key_bytes, signed_string)# 4. Encode: base64(hmac_bytes)# 5. Compare with each "v1,<value>" in the svix-signature header
Always verify signatures before processing the payload. This prevents replay attacks and ensures events cannot be forged by third parties.
The svix-id header is stable across retries — the same logical event always carries the same ID. Store received IDs and skip duplicates to make your handler idempotent.
Open Wearables (via Svix) retries failed deliveries automatically with exponential back-off. A delivery is considered failed when your endpoint returns a non-2xx status code or does not respond within the timeout.
Retry schedule
Svix retries each failed message at increasing intervals. If all retries are exhausted the message is marked as failed in delivery history — you can inspect it and manually trigger a resend from the Svix dashboard.
Expected endpoint behaviour
Respond with a 2xx status code as quickly as possible (before doing any heavy processing).
Offload slow work to a background queue — process the event asynchronously.
Return 2xx even for events you choose to ignore (otherwise they’ll be retried).
Webhook availability
Data ingestion is never blocked by webhook failures — if delivery infrastructure is temporarily unavailable, data continues to be stored and events are queued for retry.
