v1 to v2 Migration Guide

This guide provides information for developers migrating from v1 to v2 of the WHOOP Developer API. The v2 API offers several improvements while maintaining compatibility with core functionality.

Overview of Changes

The v2 API provides several improvements over the v1 API:

• More consistent resource paths and naming
• Enhanced data modeling with more precise types
• UUID-based identification for certain resources
• Better client/server error handling
• More consistent pagination behavior
• Improved OpenAPI specifications and documentation
• Recovery activities are included in the Workouts endpoint

Endpoint Changes

v1 Endpoint	v2 Endpoint	Notes
v1/activity/sleep	v2/activity/sleep	Same structure, but UUID instead of long for sleepId
v1/activity/workout	v2/activity/workout	Same structure, but UUID instead of long for workoutId
v1/cycle	v2/cycle	Enhanced with v2/cycle/{cycleId}/sleep relationship
v1/recovery	v2/recovery	Improved scoring model

Data Model Changes

Common Changes

• IDs changed from long to UUID for some resources (e.g., Sleep, Workout)
• More consistent Optional handling
• Added activityV1Id fields to maintain backwards compatibility
• Timezone handling standardized to UTC when not specified

Sleep Model

• v1: long getId() → v2: UUID getId() for uniquely identifying sleep
• Added Optional<Integer> getActivityV1Id() to maintain backwards compatibility
• Enhanced sleep stage information
• More detailed sleep quality metrics
• Improved scoring model with additional fields

Workout Model

• v1: long getId() → v2: UUID getId() for uniquely identifying workouts
• Added Optional<Integer> getActivityV1Id() to maintain backwards compatibility with v1 IDs
• More consistent handling of Optional fields
• Improved workout scoring model with properly typed Optional values

Cycle Model

• Consistent score state handling between v1 and v2
• Score is only created when all required data is present (avg heart rate, max heart rate, kilojoules, and strain)
• No fallback values for missing data (maintains backwards compatibility)
• Added relationship to Sleep data through v2/cycle/{cycleId}/sleep

Authentication and Security

• Consistent scope naming and usage
• Same OAuth 2.0 flow with improved token validation
• Security scopes defined as constants in DeveloperApiConstants (e.g., READ_SLEEP, READ_CYCLES, READ_WORKOUT)

Webhook Model Versions

WHOOP now supports two webhook model versions that align with the API versions. For detailed webhook documentation, see Webhooks.

v1 Webhooks (Default)

• Use integer IDs for identifying resources
• Compatible with existing v1 integrations
• Align with v1 API endpoints

v2 Webhooks

• Use UUID identifiers instead of integer IDs for activity webhooks (workout and sleep events)
• Recovery webhooks use the UUID identifier of the sleep associated with the recovery in v2 model versions
• Align with v2 API endpoints and data models

Key Differences

Event Type	v1 Webhook ID	v2 Webhook ID	Notes
workout.updated/deleted	Integer workout ID	UUID workout ID	Corresponds to v2 workout endpoints
sleep.updated/deleted	Integer sleep ID	UUID sleep ID	Corresponds to v2 sleep endpoints
recovery.updated/deleted	Integer cycle ID	UUID sleep ID	Recovery webhooks use UUID sleep IDs in v2 versions

Configuring Webhook Versions

In the WHOOP Developer Dashboard, you can configure the model version for each webhook URL:

1. Navigate to your app settings in the WHOOP Developer Dashboard
2. In the Webhooks section, add or edit webhook URLs
3. Select v1 or v2 from the Model Version dropdown for each URL
4. Save your app configuration

Migration Strategy for Webhooks

When migrating from v1 to v2:

1. Set up a test webhook URL with v2 model version to test the new UUID format
2. Update your webhook handler to process UUID identifiers for activity events
3. Align with your API version: Use v2 webhooks if you're calling v2 API endpoints
4. Gradual migration: You can run both v1 and v2 webhooks simultaneously during testing

Example v1 vs v2 Webhook Payloads:

v1 Webhook (sleep.updated):

{
  "user_id": 456,
  "id": 1234,
  "type": "sleep.updated",
  "trace_id": "e369c784-5100-49e8-8098-75d35c47b31b"
}

v2 Webhook (sleep.updated):

{
  "user_id": 456,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "sleep.updated", 
  "trace_id": "e369c784-5100-49e8-8098-75d35c47b31b"
}

Webhook and API Alignment

The webhook model version you choose should align with the API version you're using:

• v1 webhooks → Use with v1 API endpoints (integer IDs)
• v2 webhooks → Use with v2 API endpoints (UUID IDs)

Migration Steps

1. Update Endpoints

Update your API client to use v2 endpoints instead of v1:

- GET /v1/activity/sleep
+ GET /v2/activity/sleep

- GET /v1/activity/sleep/{sleepId}
+ GET /v2/activity/sleep/{sleepId}

- GET /v1/activity/workout
+ GET /v2/activity/workout

- GET /v1/activity/workout/{workoutId}
+ GET /v2/activity/workout/{workoutId}

2. Update ID Handling

Resource IDs are now UUIDs instead of longs for certain resources:

- long sleepId = 12345;
+ UUID sleepId = UUID.fromString("ecfc6a15-4661-442f-a9a4-f160dd7afae8");

- long workoutId = 56789;
+ UUID workoutId = UUID.fromString("7bfc6a15-5521-612f-b9a4-e274dd7afae9");

Use the activityV1Id field if you need backwards compatibility with your existing IDs.

3. Update Webhook Configuration (If Using Webhooks)

If you're using webhooks, consider updating to v2 webhook model version:

1. Test first: Set up a separate webhook URL with v2 model version
2. Update webhook processing: Modify your webhook handler to process UUID identifiers
3. Switch webhook version: Update your production webhook URL to use v2 model version
4. Verify alignment: Ensure webhook version matches the API version you're calling

See the Webhooks documentation for detailed configuration instructions.

4. Update Response Handling

Adjust your code to handle the updated data models:

• Check for presence of fields with Optional.isPresent() rather than null checks
• Use Optional.map(), Optional.orElse(), etc. for proper Optional handling
• Use the new field names and structures
• Take advantage of additional fields and relationships available in v2

5. Testing

• Test your integration thoroughly with both v1 and v2 endpoints
• Compare responses for consistency before fully migrating
• If using webhooks, test both v1 and v2 webhook formats
• Use the v2 API documentation for field details and required parameters

Benefits of Migrating

• More consistent API behavior
• Better data models and relationships
• Improved error handling
• Webhook model versions that align with API versions
• Future features will be added to v2 first
• Long-term support and improvement path

Deprecation Timeline

The v1 API will continue to be supported, but all new features will be added to v2 first. We recommend migrating to v2 as soon as possible to take advantage of improvements and new functionality.