Notifications

You may subscribe your users to get notifications for certain classes of errors or new items to be sent directly to your site via WebHook or collected periodically.

For webhooks, the basic workflow for this is that you would provide us with a URL to be notified and potentially a filter. You can choose to be notified with each item or as a generic notification. Your site must use SSL using a non-self-served certificate. You should not whitelist our IP addresses as we updated our addresses regularly for scalability reasons. Each message sent to you is signed with your OAuth2 Secret Key, as described in Verifying Webhook Requests.

For pull notifications, you optionally provide us with a filter, and then periodically collect the notifications, acquire the data, and delete any claims.

Once notifications are enabled for your account, then you can subscribe a user using the API below. When the user adds a new item, this item would be sent or made available to your notification system.

If your account has multiple notification rules, you only need to subscribe once per user.

The request to your server will be a POST request containing:

Your server must respond with a 200 or 201. If your server responds with a 403, the user will be automatically unsubscribed. All other error codes will be retried up-to a predefined maximum attempts.

Verifying Webhook Requests

Every webhook request carries three headers that let you confirm it came from FitnessSyncer and has not been altered or replayed:

• X-FitnessSyncer-Timestamp: the time the request was signed, in seconds since the Unix epoch.
• X-FitnessSyncer-Signature-256: the Base64-encoded HMAC-SHA256 of the timestamp, a period, and the exact bytes of the request body as received, using your OAuth2 Secret Key as the key.
• X-FitnessSyncer-Signature: the Base64-encoded HMAC-SHA1 of the URL-encoded context body part, using your OAuth2 Secret Key as the key. This covers only the context part, not the item, JSON or file, and is kept unchanged for compatibility with existing integrations.

We recommend verifying X-FitnessSyncer-Signature-256. To do so:

1. Read the raw request body before any multipart or form parsing, since parsing and re-serializing the body will not reproduce the bytes that were signed.
2. Compute the HMAC-SHA256 of the X-FitnessSyncer-Timestamp value, followed by a period (.), followed by the raw body, keyed by your OAuth2 Secret Key, and Base64-encode the result.
3. Compare your result with X-FitnessSyncer-Signature-256 using a constant-time comparison, such as hmac.compare_digest in Python, crypto.timingSafeEqual in Node.js or MessageDigest.isEqual in Java, and reject the request if they differ.
4. Reject the request if the timestamp is more than 5 minutes older or newer than your server’s clock, so a captured request cannot be replayed later.

Learning if there is a subscription

To figure out if there is an active subscription, use this method. You may periodically wish to do this in the event of errors notifying your service of a subscription.

curl -H "Authorization: Bearer AccessToken" "https://api.fitnesssyncer.com/api/subscriptions/"

Request Parameters

None

Response

The response to this query will be a JSON object with Subscription.

If there is not an active subscription, the response will be a 404.

Sample

{"notificationKey": "1bd2a05e-7c1e-40fc-b3de-57f0b1672861"}

Subscribing

To subscribe a user for notifications, you can use this API.

Request Parameters

None

Response

The response to this query will be a JSON object with Subscription.

Sample

{"notificationKey": "1bd2a05e-7c1e-40fc-b3de-57f0b1672861"}

Unsubscribing

To unsubscribe a user from notifications, use this endpoint.

Note that if your server responds with a 403 error when it is notified, they will be automatically unsubscribed.

Unsubscribe a user as part of deregistering them such as when they stop using your application, or delete their account with you, along with revoking their token.

curl -X DELETE -H "Authorization: Bearer AccessToken" "https://api.fitnesssyncer.com/api/subscriptions/notificationKey"

Request Parameters

None

Response

The response to this query will be a JSON object with a status indicating success.

Sample

{"status": "OK"}

Pull Notifications: Claiming Notifications

For pull notifications, you will need to claim notifications, process the notifications, and then delete the claim. If you do not delete the claim, the notification will eventually come back to you.

Note that we will only provide you with a maximum of 100 notifications per response. If you have more than 100 notifications, you will need to requery the API for each notification.

Request Parameters

None

Response

If the response code is a 204, there currently are no notifications available.

If the response code is a 200, the body of the JSON object will have Notification result.

Sample

{
    "claim": "1bd2a05e-7c1e-40fc-b3de-57f0b1672861",
    "notifications": {
        "items": [{
            "notificationKey": "1bd2a05e-7c1e-40fc-b3de-57f0b1672861",
            "sourceId": "b16e8e9c-0f44-48a4-a717-1ca12c0d959a",
            "itemId": "1762710031"
        }],
        "errors": []
    }
}

Pull Notifications: Deleting Notifications

Once you have successfully processed a notification, you must delete it. Failure to do so will result in the same notification being delivered to you again.

curl -X DELETE -H "Authorization: Bearer AccessToken" "https://api.fitnesssyncer.com/api/notifications/claim"

Request Parameters

None

Response

The response to this query will be a JSON object with a status indicating success.

Sample

{"status": "OK"}

Types

Subscription

Notification

Notifications

Notification Item

Notification Error Item