Skip to content

webhook-setup.md

Latest commit

 

History

History
494 lines (352 loc) · 14.8 KB

webhook-setup.md

File metadata and controls

494 lines (352 loc) · 14.8 KB

Fitness Tracker Webhook Setup Guide

This guide provides step-by-step instructions for configuring webhooks in each fitness tracker provider's developer portal to enable real-time data synchronization with HealthDecoder.

Table of Contents

Prerequisites

Before configuring webhooks, ensure you have:

  1. A Supabase project with Edge Functions deployed
  2. Your Supabase project ID (found in project settings)
  3. Developer accounts with each fitness tracker provider
  4. The webhook Edge Functions deployed:
    • fitbit-webhook
    • whoop-webhook
    • oura-webhook

Webhook URL Format

All webhook URLs follow this pattern:

https://[YOUR-PROJECT-ID].supabase.co/functions/v1/[provider]-webhook

Replace [YOUR-PROJECT-ID] with your actual Supabase project reference ID.

Fitbit Webhook Setup

Overview

Fitbit uses a Subscription API that sends push notifications when user data changes. The webhook endpoint must handle both verification requests (GET) and notification delivery (POST).

Webhook URL

https://[YOUR-PROJECT-ID].supabase.co/functions/v1/fitbit-webhook

Step 1: Create a Fitbit Developer Account

  1. Go to dev.fitbit.com
  2. Sign in with your Google account (required for Fitbit developer access)
  3. Navigate to Manage > Register An App

Step 2: Register Your Application

  1. Fill in the application details:

    • Application Name: Your app name
    • Description: Brief description
    • Application Website URL: Your website
    • Organization: Your organization name
    • Organization Website URL: Your organization website
    • Terms of Service URL: Your ToS URL
    • Privacy Policy URL: Your privacy policy URL
    • OAuth 2.0 Application Type: Select "Server"
    • Callback URL: Your OAuth callback URL
    • Default Access Type: Select "Read-Only" or "Read & Write" as needed

  2. Click Register to create the application

Step 3: Configure the Subscriber Endpoint

  1. In your application settings, locate the Subscription section
  2. Enter your webhook URL in the Subscriber Endpoint field: 
    https://[YOUR-PROJECT-ID].supabase.co/functions/v1/fitbit-webhook
  3. Note the Subscriber Verification Code displayed (you'll need this for the environment variable)

Step 4: Set Environment Variables in Supabase

Set the following secret in your Supabase project:

supabase secrets set FITBIT_SUBSCRIBER_VERIFICATION_CODE="your-verification-code-here"

This code is used for:

  • Verification requests: Fitbit sends GET requests with ?verify=CODE to confirm your endpoint
  • Signature validation: Used to verify webhook POST request signatures via HMAC-SHA256

Step 5: Verify the Endpoint

  1. Click the Verify button in the Fitbit developer dashboard
  2. Fitbit will send two GET requests to your endpoint:
    • One with the correct verification code (expect HTTP 204 response)
    • One with an incorrect code (expect HTTP 404 response)
  3. Both requests must respond correctly within 5 seconds
  4. If successful, your endpoint will be marked as "Verified"

Step 6: Create Subscriptions

After verification, you can create subscriptions programmatically using the Fitbit API. Subscribe to the following collection types:

Collection Type Description Maps To
activities Daily activity summaries summary sync
sleep Sleep data sleep sync
body Body measurements summary sync
weight Weight measurements summary sync

Signature Verification Details

Fitbit signs webhook payloads using HMAC-SHA256:

  • Header: X-Fitbit-Signature
  • Algorithm: HMAC-SHA256
  • Key: SUBSCRIBER_VERIFICATION_CODE + "&"
  • Data: request_body + "&"
  • Format: Base64-encoded signature

Events Received

The webhook receives an array of notifications:

[
  {
    "collectionType": "activities",
    "date": "2025-01-15",
    "ownerId": "ABC123",
    "ownerType": "user",
    "subscriptionId": "1"
  }
]

Reference Documentation

Whoop Webhook Setup

Overview

Whoop webhooks notify your application when user data is created, updated, or deleted. The webhook endpoint only handles POST requests (no verification handshake required).

Webhook URL

https://[YOUR-PROJECT-ID].supabase.co/functions/v1/whoop-webhook

Step 1: Create a Whoop Developer Account

  1. Go to developer.whoop.com
  2. Sign in with your Whoop account credentials
  3. Navigate to the Dashboard

Step 2: Create an Application

  1. Click Create App in the dashboard
  2. Fill in the application details:
    • App Name: Your application name
    • Description: Brief description
    • Redirect URI: Your OAuth callback URL
  3. Save the application

Step 3: Configure the Webhook URL

  1. In your application settings, scroll to the Webhooks section
  2. Add your webhook URL: 
    https://[YOUR-PROJECT-ID].supabase.co/functions/v1/whoop-webhook
  3. Select the Model Version (choose v2 for new integrations)
  4. Save your changes

Step 4: Set Environment Variables in Supabase

Set the following secret in your Supabase project:

supabase secrets set WHOOP_CLIENT_SECRET="your-client-secret-here"

Find your Client Secret in the app settings of the Whoop Developer Dashboard. This is used for webhook signature verification.

Signature Verification Details

Whoop signs webhook payloads using HMAC-SHA256:

  • Signature Header: X-WHOOP-Signature
  • Timestamp Header: X-WHOOP-Signature-Timestamp (milliseconds since epoch)
  • Algorithm: HMAC-SHA256
  • Key: Your CLIENT_SECRET
  • Data: timestamp + request_body (concatenated)
  • Format: Base64-encoded signature

Events Subscribed

All configured webhook URLs receive all event types:

Event Type Description Maps To
recovery.updated Recovery data updated recovery sync
recovery.deleted Recovery data deleted -
sleep.updated Sleep data updated sleep sync
sleep.deleted Sleep data deleted -
workout.updated Workout data updated workout sync
workout.deleted Workout data deleted -

Event Payload Format

{
  "user_id": 12345,
  "type": "recovery.updated",
  "id": 67890,
  "trace_id": "abc-123-def"
}

Response Requirements

  • Return HTTP 2XX status code within 1 second
  • For async processing, acknowledge immediately and queue the work
  • Failed deliveries are retried up to 5 times over approximately 1 hour

Reference Documentation

Oura Webhook Setup

Overview

Oura webhooks notify your application when user data is available. The webhook endpoint must handle both challenge verification (GET) and event delivery (POST).

Webhook URL

https://[YOUR-PROJECT-ID].supabase.co/functions/v1/oura-webhook

Step 1: Create an Oura Developer Account

  1. Go to cloud.ouraring.com
  2. Sign in with your Oura account
  3. Navigate to Applications or API Applications

Step 2: Register Your Application

  1. Click Create New Application
  2. Fill in the application details:
    • Application Name: Your app name
    • Description: Brief description
    • Redirect URI: Your OAuth callback URL
    • Webhook URL: Your webhook endpoint (can be added later)
  3. Note your Client ID and Client Secret

Step 3: Configure the Webhook URL

  1. In your application settings, locate the webhook configuration section
  2. Enter your webhook URL: 
    https://[YOUR-PROJECT-ID].supabase.co/functions/v1/oura-webhook
  3. Note the Webhook Secret provided (for signature verification)
  4. Save your configuration

Step 4: Set Environment Variables in Supabase

Set the following secrets in your Supabase project:

supabase secrets set OURA_CLIENT_ID="your-client-id-here"
supabase secrets set OURA_CLIENT_SECRET="your-client-secret-here"
supabase secrets set OURA_WEBHOOK_SECRET="your-webhook-secret-here"

Challenge Verification

When you configure or update the webhook URL, Oura sends a verification challenge:

  • Method: GET
  • Query Parameter: ?challenge=RANDOM_STRING
  • Expected Response: Echo back the challenge string with HTTP 200
  • Content-Type: text/plain

The webhook function handles this automatically by returning the challenge parameter value.

Signature Verification Details

Oura signs webhook payloads using HMAC-SHA256:

  • Header: X-Oura-Signature
  • Algorithm: HMAC-SHA256
  • Key: Your WEBHOOK_SECRET
  • Data: Raw request body
  • Format: Base64-encoded signature

Events Subscribed

Data Type Description Maps To
sleep Sleep sessions sleep sync
daily_sleep Daily sleep summaries sleep sync
daily_activity Daily activity summaries activity sync
daily_readiness Daily readiness scores readiness sync
workout Workout sessions workout sync
session Activity sessions workout sync
daily_spo2 Blood oxygen data readiness sync

Event Payload Format

Events are delivered as an array:

[
  {
    "event_type": "create",
    "data_type": "daily_sleep",
    "user_id": "OURA_USER_ID",
    "event_timestamp": "2025-01-15T08:30:00Z"
  }
]

Response Requirements

  • Return HTTP 200 status code to acknowledge receipt
  • Process events asynchronously if needed
  • Missing signature results in logged warning but accepted payload

Reference Documentation

Environment Variables Summary

Required Supabase Secrets

Variable Provider Purpose
FITBIT_SUBSCRIBER_VERIFICATION_CODE Fitbit Endpoint verification and signature validation
WHOOP_CLIENT_SECRET Whoop Webhook signature verification
OURA_CLIENT_ID Oura OAuth authentication
OURA_CLIENT_SECRET Oura OAuth authentication
OURA_WEBHOOK_SECRET Oura Webhook signature verification

Automatic Supabase Variables

These are automatically available in Edge Functions:

Variable Purpose
SUPABASE_URL Supabase project URL
SUPABASE_SERVICE_ROLE_KEY Service role key for internal API calls

Setting Secrets

Use the Supabase CLI to set secrets:

# Set individual secrets
supabase secrets set VARIABLE_NAME="value"

# Set multiple secrets from a file
supabase secrets set --env-file .env.secrets

Troubleshooting

Fitbit

Verification Failed

  • Ensure your endpoint responds within 5 seconds
  • Check that correct verification code returns HTTP 204
  • Check that incorrect verification code returns HTTP 404
  • Verify the endpoint is publicly accessible (no auth required for verification)

Signature Validation Failed

  • Confirm FITBIT_SUBSCRIBER_VERIFICATION_CODE matches the dashboard value
  • Check that you're appending & to both the key and body before signing

Subscriber Disabled

  • Fitbit automatically disables subscribers that fail to respond with HTTP 204 within 5 seconds
  • Check your Edge Function logs for errors
  • Re-verify the endpoint after fixing issues

Whoop

Not Receiving Webhooks

  • Confirm the webhook URL is saved in the dashboard
  • Ensure at least one user has authenticated with your app
  • Check that your endpoint returns HTTP 2XX within 1 second

Signature Mismatch

  • Verify WHOOP_CLIENT_SECRET is set correctly
  • Ensure you're concatenating timestamp + body (not body + timestamp)
  • Check timestamp header is being read correctly

Oura

Challenge Verification Failed

  • Ensure your endpoint returns the challenge string exactly as received
  • Response must be plain text, not JSON
  • HTTP status must be 200

Signature Validation Failed

  • Confirm OURA_WEBHOOK_SECRET is set correctly
  • Check that you're using the raw request body for signing

General Debugging

Check Edge Function Logs

supabase functions logs fitbit-webhook --tail
supabase functions logs whoop-webhook --tail
supabase functions logs oura-webhook --tail

Test Endpoint Accessibility

# Test Fitbit verification (should return 404 for wrong code)
curl "https://[PROJECT-ID].supabase.co/functions/v1/fitbit-webhook?verify=wrong-code"

# Test Oura challenge (should echo back the challenge)
curl "https://[PROJECT-ID].supabase.co/functions/v1/oura-webhook?challenge=test123"

Verify Secrets Are Set

supabase secrets list

Security Best Practices

  1. Always validate signatures - Never skip signature verification in production
  2. Use HTTPS - All webhook URLs must use HTTPS (enforced by all providers)
  3. Acknowledge quickly - Return success status immediately, process asynchronously
  4. Log webhook events - The Edge Functions log to ingestion_log table for debugging
  5. Monitor failures - Set up alerts for repeated webhook failures
  6. Rotate secrets - Periodically rotate webhook secrets and update all configurations

Quick Reference

Webhook URLs

Provider URL Pattern
Fitbit https://[PROJECT-ID].supabase.co/functions/v1/fitbit-webhook
Whoop https://[PROJECT-ID].supabase.co/functions/v1/whoop-webhook
Oura https://[PROJECT-ID].supabase.co/functions/v1/oura-webhook

Response Codes

Provider Success Verification Success Verification Failure
Fitbit 204 204 404
Whoop 200 N/A N/A
Oura 200 200 (echo challenge) 404

Signature Headers

Provider Signature Header Timestamp Header
Fitbit X-Fitbit-Signature N/A
Whoop X-WHOOP-Signature X-WHOOP-Signature-Timestamp
Oura X-Oura-Signature N/A