Strava Webhooks - Open Wearables

Overview

Strava webhooks notify Open Wearables when activities are created, updated, or deleted. The webhook uses a single endpoint with two methods:

GET: Subscription verification during webhook setup
POST: Activity event notifications

These endpoints are designed to be called by Strava’s servers, not by your application. Configure the webhook subscription via the Strava API Settings.

Webhook Verification (GET)

Endpoint

GET /api/v1/webhooks/strava/webhook

Description

When creating a webhook subscription, Strava sends a GET request to verify your endpoint. You must echo back the hub.challenge parameter if the hub.verify_token matches your configured token.

Query Parameters

hub.mode

string

required

Always “subscribe” during verification

hub.challenge

string

required

Random string to echo back for verification

hub.verify_token

string

required

Your verification token (configured in Strava API settings)

Response

hub.challenge

string

The challenge string echoed back to Strava

Example Request

Strava Verification Request

GET /api/v1/webhooks/strava/webhook?hub.mode=subscribe&hub.challenge=15f7d1a91c1f40&hub.verify_token=your_verify_token

Example Response

200 - Success

{
  "hub.challenge": "15f7d1a91c1f40"
}

403 - Forbidden

{
  "detail": "Invalid verify token"
}

Event Notification (POST)

Endpoint

POST /api/v1/webhooks/strava/webhook

Description

Receives notifications when activities are created, updated, or deleted. The webhook contains minimal information (activity ID, owner ID, event type) - full activity data must be fetched separately using the Strava API.

Request Body

Strava sends a JSON payload with event details.

Example Event Payload

{
  "object_type": "activity",
  "object_id": 12345678,
  "aspect_type": "create",
  "owner_id": 87654321,
  "subscription_id": 999,
  "event_time": 1710523200
}

Request Fields

object_type

string

Type of object - currently always “activity” or “athlete”

object_id

integer

Strava activity ID

aspect_type

string

Event type:

create: New activity created
update: Activity updated
delete: Activity deleted

owner_id

integer

Strava athlete (user) ID who owns the activity

subscription_id

integer

Your webhook subscription ID

event_time

integer

Unix timestamp when the event occurred

Response

Always returns HTTP 200 to acknowledge receipt. Strava will retry if non-200 status is returned.

status

string

Status of event processing

message

string

Human-readable message

Example Responses

200 - Activity Created

{
  "status": "processed",
  "message": "Activity 12345678 created for user 550e8400-e29b-41d4-a716-446655440000"
}

200 - Activity Updated

{
  "status": "processed",
  "message": "Activity 12345678 updated for user 550e8400-e29b-41d4-a716-446655440000"
}

200 - Activity Deleted

{
  "status": "processed",
  "message": "Activity 12345678 deleted for user 550e8400-e29b-41d4-a716-446655440000"
}

200 - User Not Found

{
  "status": "skipped",
  "message": "No connection found for Strava user 87654321"
}

Event Types

Activity Created

Triggered when a user uploads or records a new activity. Open Wearables will:

Verify the user has an active Strava connection
Fetch full activity details from Strava API
Save activity as EventRecord in the database

Activity Updated

Triggered when a user edits an activity (title, description, privacy, etc.). Open Wearables will:

Fetch updated activity details from Strava API
Update the corresponding EventRecord

Activity Deleted

Triggered when a user deletes an activity. Open Wearables will:

Find the corresponding EventRecord
Mark it as deleted or remove it (depending on configuration)

Athlete Updates

Triggered when athlete profile is updated (deauthorization, privacy changes). Open Wearables will:

Update connection status if deauthorized
Update privacy settings if changed

Health Check

Endpoint

GET /api/v1/webhooks/strava/health

Description

Health check endpoint for monitoring webhook availability.

Response

200 - OK

{
  "status": "ok",
  "service": "strava-webhooks"
}

Setup Guide

1. Create Webhook Subscription

Use the Strava API to create a subscription:

Create Subscription

curl -X POST https://www.strava.com/api/v3/push_subscriptions \
  -F client_id=YOUR_CLIENT_ID \
  -F client_secret=YOUR_CLIENT_SECRET \
  -F callback_url=https://your-domain.com/api/v1/webhooks/strava/webhook \
  -F verify_token=YOUR_VERIFY_TOKEN

2. Verify Subscription

Strava will immediately call your GET endpoint to verify the subscription. Ensure your server:

Accepts the hub.mode, hub.challenge, and hub.verify_token parameters
Validates the verify token matches your configured value
Returns the hub.challenge in the response

3. Handle Events

Once verified, Strava will POST events to your webhook URL. Your server must:

Always return HTTP 200 (even for errors)
Process events asynchronously
Handle rate limits when fetching activity details

4. Test the Webhook

Create a test activity in your Strava account and verify:

Webhook receives POST request
Activity is fetched and saved correctly
No errors are logged

Rate Limits

When fetching activity details via Strava API:

100 requests per 15 minutes
1000 requests per day

Open Wearables handles rate limiting automatically by:

Queuing webhook events
Implementing exponential backoff
Respecting Strava’s rate limit headers

Error Handling

Always returns HTTP 200 to prevent Strava from retrying
Errors are logged internally and tracked via monitoring
User not found errors are normal (user may have disconnected)
Activity fetch failures are retried with exponential backoff
Duplicate events are deduplicated automatically

Security

Webhook endpoint is public (no API key required)
Verify token prevents unauthorized subscription creation
Activity data is fetched using user’s OAuth access token
Validate event authenticity by checking subscription_id

Troubleshooting

Webhook Not Receiving Events

Verify subscription is active: GET https://www.strava.com/api/v3/push_subscriptions
Check callback URL is publicly accessible
Ensure webhook returns HTTP 200
Review Strava API logs in developer dashboard

Duplicate Events

Strava may send duplicate events if:

Webhook response is slow (> 2 seconds)
Non-200 status code returned
Network timeout occurs

Open Wearables deduplicates events using activity ID and timestamp.

Missing Activities

If activities aren’t appearing:

Check user’s Strava connection is active
Verify OAuth token hasn’t expired
Check activity privacy settings (private activities may be excluded)
Review error logs for API rate limiting

Sync Data - Manually trigger Strava sync
List Connections - View user’s Strava connection status

Authentication

Users

OAuth

Health Data

Connections

Webhooks

​Overview

​Webhook Verification (GET)

​Endpoint

​Description

​Query Parameters

​Response

​Example Request

​Example Response

​Event Notification (POST)

​Endpoint

​Description

​Request Body

​Request Fields

​Response

​Example Responses

​Event Types

​Activity Created

​Activity Updated

​Activity Deleted

​Athlete Updates

​Health Check

​Endpoint

​Description

​Response

​Setup Guide

​1. Create Webhook Subscription

​2. Verify Subscription

​3. Handle Events

​4. Test the Webhook

​Rate Limits

​Error Handling

​Security

​Troubleshooting

​Webhook Not Receiving Events

​Duplicate Events

​Missing Activities

​Related Endpoints

Build docs developers (and LLMs) love

Overview

Webhook Verification (GET)

Endpoint

Description

Query Parameters

Response

Example Request

Example Response

Event Notification (POST)

Endpoint

Description

Request Body

Request Fields

Response

Example Responses

Event Types

Activity Created

Activity Updated

Activity Deleted

Athlete Updates

Health Check

Endpoint

Description

Response

Setup Guide

1. Create Webhook Subscription

2. Verify Subscription

3. Handle Events

4. Test the Webhook

Rate Limits

Error Handling

Security

Troubleshooting

Webhook Not Receiving Events

Duplicate Events

Missing Activities

Related Endpoints