Skip to main content
When testing webhooks (Garmin OAuth callback, Garmin data push) or the Apple Health SDK, you need to expose your local backend to the internet. ngrok provides a simple solution with minimal configuration.
Why might ngrok be needed for the OAuth flow? Because Garmin’s OAuth callback requires HTTPS. Other currently supported cloud providers work with HTTP, so localhost is fine.

​
Quick Start

1

Install ngrok

Download from ngrok.com or use a package manager:
# macOS
brew install ngrok

# Or download directly
2

Start your backend

Ensure your Open Wearables backend is running locally (typically on port 8000):
docker compose up
3

Expose with ngrok

Run ngrok to create a public tunnel:
ngrok http 8000
4

Use the public URL

ngrok will display a public URL like:
Forwarding  https://abc123.ngrok-free.app -> http://localhost:8000
Use this HTTPS URL for:

​
Common Use Cases

Garmin (requires HTTPS):Garmin OAuth requires HTTPS, so you need ngrok:
  1. Start ngrok: ngrok http 8000
  2. Copy the HTTPS URL (e.g., https://abc123.ngrok-free.app)
  3. Use it as the redirect_uri parameter:
curl "http://localhost:8000/api/v1/oauth/garmin/authorize?user_id=USER_ID&redirect_uri=https://abc123.ngrok-free.app/oauth/callback" \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY"
Polar & Suunto (HTTP works):These providers don’t require HTTPS, so you can test locally without ngrok:
# Use localhost directly
curl "http://localhost:8000/api/v1/oauth/polar/authorize?user_id=USER_ID&redirect_uri=http://localhost:8000/oauth/callback" \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY"
For testing webhook endpoints (e.g., Garmin data push):
  1. Expose your backend: ngrok http 8000
  2. Configure the webhook URL in your provider settings:
    • Garmin: Use https://abc123.ngrok-free.app/api/v1/garmin/webhooks/push
    • Other providers: Similar pattern
When testing Apple Health SDK or mobile app integrations:
  1. Start ngrok: ngrok http 8000
  2. Configure your mobile app to use the ngrok URL:
    • Update API base URL to https://abc123.ngrok-free.app
    • Same approach

​
Tips

Static domain: For a consistent URL that doesn’t change on restart, you can set a custom domain in ngrok (requires account):
ngrok http 8000 --domain=your-custom-domain.ngrok-free.app
Security: Only use ngrok for development/testing. Never expose production backends through ngrok without proper authentication and rate limiting.