Using Subscriptions

Everytime a Fitbit user opens the Fitbit mobile application, the Fitbit device automatically syncs to fitbit.com. The average user syncs their Fitbit device several times a day, and the user may manually log additional exercises and nutritional information. Meanwhile, other users may sync their device sporadically, uploading as much as a week's worth of data all at once. Because of the infrequency of updates, Fitbit has developed a subscription service allowing 3rd-party applications to be notified when a Fitbit user has updated their data. This prevents the need for you to develop a polling or scheduling system looking for new data.

Introduction to Subscriptions

Here are some terms that will be used throughout this section

To describe how subscriptions work, the developer will create a subscriber endpoint and register the endpoint through their application’s configuration within the Fitbit developer’s portal. This subscriber endpoint URL must be accessible to our servers, be able to handle the incoming HTTP POST request and process the content of the request (JSON).

When a user consents to share their data with the developer’s application, the application should create a subscription request for a specific type of data or collection. Once, Fitbit detects updates to the user’s data, a webhook notification is sent in near real-time to the subscriber endpoint URL for processing. These notifications only alert the application to the fact that certain data has been updated. The application must make the appropriate API calls to retrieve the actual data.

TIP: Multiple subscriber endpoints can be used to compartmentalize the notifications between a subset of members or data types.

Implementing the Subscription API

Use the following steps to implement the Subscription API:

1. Create a web service endpoint that can receive the HTTPS POST notifications described in Notifications. Make sure this endpoint is accessible from fitbit.com servers.
2. Configure a subscriber to point to this endpoint as described in Configure a Subscriber.
3. Verify your subscriber endpoint as described in Verify a Subscriber. This will require adding code to respond correctly to a verification code.
4. Add subscriptions as described in Add a Subscription.

Subscribers

Configuring a Subscriber

The subscriber is an endpoint that receives notifications when a user adds, deletes or updates their data. The subscriber URL is added to the application configuration at https://dev.fitbit.com/apps. The application may have multiple subscribers, but one subscriber endpoint must be designated as the default subscriber. The default subscriber is used if no subscriber is specified when Creating a Subscription. A subscriber ID is required, which is used to specify which subscriber the subscription is being added. If a subscriber ID is not provided, one will be automatically assigned by Fitbit.

TIP: To learn how to improve the securty of your subscriber, see Subscriber Security.

Subscriber endpoints have the following parameters:

Using HTTPS

Fitbit requires Transport Layer Security protocol - TLSv1.2 for the subscriber endpoints. TLS+SNI is not supported. Self-signed certificates and all versions of SSL are also not supported.

Verifying a Subscriber

All new or edited subscriber endpoint configurations must be verified to receive webhook notifications. When the "verify" button is pressed, Fitbit sends 2 GET requests to the subscriber endpoint, each containing the "verify" query string parameter. One request has the verify parameter value equal to the correct verification code (found under the verify button). The subscriber should respond with a 204. The other endpoint has the verify parameter value intentionally incorrect, and the subscriber should respond with a 404.

For example, the following should result with a 204:

GET https://yourapp.com/subscriber_endpoint?verify=correctVerificationCode

And the following should result with a 404:

GET https://yourapp.com/subscriber_endpoint?verify=incorrectVerificationCode

If both requests respond appropriately, the subscriber is marked as verified on the application details page. If Fitbit receives an incorrect response or it takes more than 5 seconds to receive the responses, the verification process will fail.

Disabled Subscribers

The application's subscriber will be automatically disabled by Fitbit if the subscriber does not properly respond to notification requests with a HTTP 204 status within 5 seconds, consistently. A subscriber is disabled when:

• It has an error rate of 10% or higher with at least 100 errors in 1 hour.
• It has not successfully delivered messages within a month.

These tolerances are subject to change without notice as necessary to protect the overall health of the Subscriptions API.

How to re-enable a subscriber

1. Go to the application's settings page
2. Click on 'details' beside the subscriber to review the logs of the most recent attempted subscription notification requests.
3. Resolve the issue with your application.
4. Click on 'edit application settings'.
5. Check the 'enabled' checkbox for your subscriber.
6. Click 'save'.

Subscriptions

Creating a Subscription

A subscription is required to receive the webhook notification about a user. Creating the subscription requires the user ID, the collectionType and the subscription ID.

The collectionType represents the type of data, or resource, which the application needs to receive notifications. To create the subscription for that collectionType, the user must have enabled the scope associated with it.

• The activities collection requires the activity scope.
• The body collection requires the weight scope.
• The foods collection requires the nutrition scope.
• The sleep collection requires the sleep scope.
• The userRevokedAccess collection requires at least one scope enabled.
• If no collection is specified, the activity, nutrition, profile, settings, sleep and weight scopes are required.

If a collectionType is not specified, a subscription will be created for all supported collectionTypes, i.e. activities, body, foods, sleep, userRevokedAccess and deletedUser. See Collection Types . When subscriptions exist for both all collectionTypes and a specific collectionType, duplicate notifications will be received. Lastly, each subscriber can have only one subscription for each user's collectionType.

The subscription ID associates a notification with a particular user stream in your application. Each subscription created must have a unique subscription ID across the entire set of subscribers and collections. The Fitbit subscription service will include this ID within the notifications about the user. The subscription ID cannot exceed 50 characters.

All notifications are sent to the default subscriber defined within the application configuration in the Fitbit developer portal. However, an application may have multiple subscribers defined for managing the notification traffic. To direct the notifications to a specific subscriber, create the subscription providing the X-Fitbit-Subscriber-Id header, specifying the ID of the subscriber which should receive the notifications.

A single user may only be subscribed to the same collection once. If a conflict arises trying to add a subscription, the server will respond with an HTTP 409 Conflict. It will still return the same response elements, but in this case, the body will tell you that the subscription already exists so that corrective action must be taken.

See Create Subscription endpoint.

Getting a List of Subscriptions

To retrieve a list of the subscriptions created for a specific user, execute the Get Subscription List endpoint. This endpoint will return the subscriptions for a single collectionType or all collectionTypes.

The collectionType represents the type of data, or resource, which the application needs to receive notifications. To list the subscriptions for that collectionType, the user must have enabled the scope associated with it.

• The activities collection requires the activity scope.
• The body collection requires the weight scope.
• The foods collection requires the nutrition scope.
• The sleep collection requires the sleep scope.
• The userRevokedAccess collection requires at least one scope enabled.
• If no collection is specified, the activity, nutrition, profile, settings, sleep and weight scopes are required.

If a collectionType is not specified, a subscription will be listed for all supported collectionTypes, i.e. activities, body, foods, sleep, userRevokedAccess and deletedUser. See Collection Types.

TIP: Have the application maintain the list of subscriptions created and use this endpoint periodically to ensure data consistency.

See Get Subscription List endpoint.

Deleting a Subscription

When the application deletes a subscription, the application will no longer receive notifications about updated data for that user. Deleting the subscription requires the user ID, the collectionType and the subscription ID.

The collectionType represents the type of data, or resource, which the application needs to receive notifications. To delete the subscription for that collectionType, the user must have enabled the scope associated with it.

• The activities collection requires the activity scope.
• The body collection requires the weight scope.
• The foods collection requires the nutrition scope.
• The sleep collection requires the sleep scope.
• The userRevokedAccess collection requires at least one scope enabled.
• If no collection is specified, the activity, nutrition, profile, settings, sleep and weight scopes are required.

If a collectionType is not specified, a subscription will be deleted for all supported collectionTypes, i.e. activities, body, foods, sleep, userRevokedAccess and deletedUser. See Collection Types.

The subscription ID associates a notification with a particular user stream in your application. Each subscription created must have a unique subscription ID across the entire set of subscribers and collections. The Fitbit subscription service will include this ID within the notifications about the user. The subscription ID cannot exceed 50 characters.

All notifications are sent to the default subscriber defined within the application configuration in the Fitbit developer portal. However, an application may have multiple subscribers defined for managing the notification traffic. To direct the notifications to a specific subscriber, create the subscription providing the X-Fitbit-Subscriber-Id header, specifying the ID of the subscriber which should receive the notifications.

The X-Fitbit-Subscriber-Id header defines the ID of the subscriber where the subscription needs to be deleted. When deleting a subscription, the default subscriber is used. If an application has multiple subscribers defined, the subscriber ID needs to be provided so the Fitbit webhook service knows which subscriber contains the subscription ID. If not specified, or the wrong subscriber ID is provided when attempting to delete the subscription, an error will be returned.

NOTE: When a user revokes consent to an application, Fitbit automatically deletes any subscriptions associated with that user and application. This prevents the application from receiving notifications for tokens that were invalidated.

See Delete Subscription endpoint.

Collection Types

Not all scopes support subscriptions or have a supported collection type. The following table outlines which scopes support subscriptions. For data sets that do not support subscriptions or do not have a collection type, see the "Additional Information" section for the respective endpoints for tips about when to download the data.

Notifications

Notification Format

An update notification request to your endpoint is defined as

Aggregation of Updates

Fitbit makes a best effort to aggregate multiple updates within a short timeframe into a single message. The maximum number of notification joined together is 100.

TIP: To learn how to improve the subscriber security when receiving notifications, see Subscriber Security.

Example

The following examples is a JSON notification where the third updated resource is for the Fitbit user X1Y2Z3 and associated activities.

[
    {
        "collectionType": "foods",
        "date": "2010-03-01",
        "ownerId": "USER_1",
        "ownerType": "user",
        "subscriptionId": "1234"
    }, {
        "collectionType": "foods",
        "date": "2010-03-02",
        "ownerId": "USER_1",
        "ownerType": "user",
        "subscriptionId": "1234"
    }, {
        "collectionType": "activities",
        "date": "2010-03-01",
        "ownerId": "X1Y2Z3",
        "ownerType": "user",
        "subscriptionId": "2345"
    }
]

Responding to a Notification

The webhook notification indicates that the resource has been added, modified, or deleted. The application should call the required endpoints to obtain the latest copy of the resource. For example, call the Get Daily Activity Summary endpoint. The application should determine which part of the resource has changed. This can be determined by comparing the new resource representation against the old resource representation.

Your server must respond to a subscription notification with HTTP 204 No Content and close the connection within 5 seconds or Fitbit will abort the connection. You should store notifications locally and later fetch the data. Do not attempt to fetch the data before responding to a notification. Doing so will cause your application to respond slowly and more importantly, trigger the Fitbit server to think your endpoint is unavailable and eventually stop your subscription. When the subscriber is disabled, an email is sent to the application owner stating the threshold was reached and the subscriber was disabled.

There are two strategies for updating your database. The first approach is to immediately retrieve the changes and update your database. The second approach is to mark the copy of the resource as dirty and retrieve the change only when the user visits your application to view the latest data. Depending on the design of your application, use the appropriate strategy. In either case, you must follow the Fitbit API throttling policy. See Rate Limit documentation for details on the throttling policy.

Notifications of Users Revoking Consent

Fitbit users have the ability to stop sharing their data with an application by revoking access (or consent) to that application through their Fitbit account settings. When the user revokes access to the application, the user's access tokens and refresh token become invalid, and the user's subscriptions are automatically deleted.

Fitbit can send a notification when a user revokes access to the application via the associated subscriber. To receive these notifications, the application needs to subscribe to the collection type userRevokedAccess. userRevokedAccess is supported for the Add Subscription, Delete Subscription and Get Subscription List endpoints. When referencing all collections with the subscription endpoints, userRevokedAccess is included.

The notification will contain the collection name, the date the user revoked access, the Fitbit user ID, the owner type and the subscription ID.

Example

[
  {
    "collectionType": "userRevokedAccess",
    "date": "2020-06-02",
    "ownerId": "X1Y2Z3",
    "ownerType": "user",
    "subscriptionId": "2345"
  }
]

Notification of Deleted Users

Fitbit has a long-standing commitment to privacy and data protection. To give our users more control over their data and support European data protection law, we send required notices through the Subscriptions API and by email to notify your application of deleted user accounts. To receive a subscription notification, your application must have one or more subscriber endpoints registered with Fitbit. This can be done as part of your initial account configuration, or via the application management view.

Example

{
    "collectionType": "deleteUser",
    "date": "2018-04-20",
    "ownerId": "X1Y2Z3",
    "ownerType": "user",
    "subscriptionId": "123"
}

NOTE: An email will always be sent in case the application misses the subscription notification. The notification is sent to the email address of the registered application's owner.

Email Example

Subject: 
Notice of deletion of the Fitbit user account {ownerId}. 

Body: 
This is an automated notice from the Fitbit API. 

You are receiving this notice because the Fitbit user {ownerId} previously 
authorized your application {applicationName} ({clientId}) to access their 
Fitbit account. 

Please be aware that the Fitbit user {ownerId} has deleted their account with us. 

Your application will receive push notifications regarding Fitbit users’ account 
deletions by subscribing to the Fitbit Subscription API documented at 
https://dev.fitbit.com/build/reference/web-api/developer-guide/using-subscriptions. 

If you have any questions, please contact us at 
https://dev.fitbit.com/build/reference/web-api/help/. 

Sincerely,
Fitbit Web API Team

Missed Notifications

Occasionally your application may miss subscription notifications due to outages and connectivity issues. The subscriptions API does not attempt to send a notification more than once. Therefore, when the user initiates a new session with your application, your application should fetch the most recent resources to be certain that the best data is presented.

Application Design

Best Practices