Data Delivery
Our platform delivers health data primarily through webhooks, with the REST API as a backup. Webhooks are the preferred and recommended mechanism for receiving real-time updates, featuring security through HMAC validation and a staggered retry logic. The API is used exclusively for specific on-demand queries, as it enforces strict rate limits and does not function as a storage solution for the client backend.
ROOK provides two primary methods for delivering health data to clients:
- ROOK Data Webhooks: Provides real-time delivery of new events or summaries.
- ROOK API: Enables on-demand access to the same data via flexible querying.
Both methods use consistent JSON schemas, ensuring seamless integration across systems.
ROOK Webhooks
Webhooks are the preferred method for receiving real-time data updates from ROOK, eliminating the need for constant polling. This section explains the types of webhooks, their setup, and key features such as security and retry logic.
Data Webhooks
- Deliver health data, such as events and summaries, in real time.
- Cover sleep, physical, and body health pillars.
- Triggered when:
- New events occur, such as step counts or heart rate measurements.
- Summaries are generated, such as daily activity or sleep reports.
- Summaries are extracted and delivered based on user-specific time zones. Refer to the Data Extraction section for more details.
- Payloads align with the JSON schemas used in the ROOK API. See the API Reference.
- Setup: Configured directly in the ROOK Portal.
Key Features of Data Webhooks
-
Security:
- Use the
X-ROOK-HASHheader for HMAC validation to ensure data authenticity. - This feature enhances security by verifying that webhook payloads originate from ROOK.
- Learn more in the HMAC validation guide.
- Use the
-
Retry Logic:
- Failed deliveries trigger retries at the following intervals:
- 2 hours, 24 hours, and 48 hours.
- If all retries fail, data is stored in buckets for client retrieval:
- Sandbox: Retained for 3 days.
- Production: Retained for 10 days.
- Learn more in the Rejected Information Project.
- Failed deliveries trigger retries at the following intervals:
Setting Up Webhooks
-
Prepare the Webhook URL:
- Ensure the URL can accept HTTP POST requests and process incoming JSON payloads.
-
Configuration:
- Set up Data Webhooks in the ROOK Portal under Set up > Webhook > Data Webhook.
- Separate configurations are required for Sandbox and Production environments.
- Notification Webhooks are activated and configured in the ROOK Portal under Set up > Webhook > Notification Webhook.
-
Response Validation:
- Respond with one of the following status codes to confirm receipt:
200 OK201 Created202 Accepted
- Invalid responses trigger retry attempts.
- Respond with one of the following status codes to confirm receipt:
Testing Tip: Use tools like Webhook.site during development to test webhook payloads.
To learn more about how to set up a webhook, read this article.
ROOK API
The ROOK API provides on-demand access to user health data, offering flexibility in querying specific metrics. It is designed to complement webhooks, not replace them, as webhooks are recommended for real-time updates.
Key Features
- On-Demand Queries: Retrieve specific data for events, summaries, and metrics when needed.
- Consistent Data Format: API responses match webhook payloads, ensuring seamless integration.
- Environment-Specific URLs:
- Sandbox:
https://api.rook-connect.review - Production:
https://api.rook-connect.com
- Sandbox:
Important Considerations When Using the ROOK API
-
Not Real-Time:
- The API does not provide real-time data. Webhooks should be used for immediate notifications of new data.
-
Rate Limits:
- The API enforces rate limits based on subscription plans. Excessive queries may result in throttling or temporary blocks.
- Typical limits include:
- Requests per minute: 60
- Requests per day: 10,000
- Specific limits may vary by plan. Contact ROOK Support for specific details.
-
Not a Storage or Backend Solution:
- The ROOK API is not intended to serve as a backend or storage system for applications.
- Applications should:
- Build a backend to store the data received from ROOK.
- Query their backend, not ROOK’s API, for user data.
-
Developer Resources:
- Access the full API reference and download the OpenAPI specification at API Reference.
The system only supports sending JSON files with a maximum size of 16 MB. Any file exceeding this limit will not be processed or delivered.
Advanced settings
For a better ROOKConnect integration experience, we recommend integrating the following add-on:
Notification Webhooks
- Provide updates about integration-specific actions, such as:
- User creation or deletion.
- Data source connections or disconnections.
- Failed data retrieval attempts.
- Two users of your account connected with the same data source account.
- Data that stopped arriving for a user.
- The delivery of a user's pre-existing data.
- Setup: Activate and configure it in the ROOK Portal under Set up > Webhook > Notification Webhook.
- Learn more in the Notification Webhook documentation.
Notification Webhook Versions
The Notification Webhook has two versions:
- Version 1 is the format that clients who already had the Notification Webhook receive. Each notice arrives as its data source publishes it: without the
X-ROOK-HASHsignature, withoutnotification_version, and with a format that can vary between data sources. Version 1 does not send the notices that were added with version 2. - Version 2 has one format for every data source, the
X-ROOK-HASHsignature, and the new noticesuser_shared_account_detected,user_pre_existing_data_deliveredanduser_data_sync_stalled.
New clients start on version 2. If you already had the Notification Webhook, you stay on version 1 and nothing changes until you decide to migrate.
To migrate, open the ROOK Portal, go to Set up > Webhook > Notification Webhook and use the button to migrate to version 2. Before you migrate, you can send a version 2 test to your endpoint to check that your code accepts the new format. While version 1 is available, you can go back to it from the same page.
Version 1 stays available for about six months from the launch of version 2, on November 13, 2026. After that period, version 1 will be retired, so migrate before then.
Verifying the Notification Signature
ROOK signs each version 2 notice with the X-ROOK-HASH header, the same header that Data Webhooks use. Verify it to confirm that ROOK sent the notice and that its identifying fields were not changed.
ROOK signs notices with the same key and the same method that it uses to sign Data Webhooks. If you already verify Data Webhooks, use the same secret_key and the same steps here: you do not need a different key for notices.
ROOK sends the header only when the client is on version 2 and has a secret_key: the same key you use to authenticate with the ROOK API (see secret_key). On version 1, or without a secret_key, the notice arrives without the header, so your code must handle a missing header.
What ROOK Signs
The header carries an HMAC-SHA256 digest as lowercase hexadecimal. To compute the same digest:
- Take the
client_uuid,user_id, andaction_datetimevalues from the body you received. - Concatenate them in that order, with no separator.
- Use an empty string for any of the three that is absent or
null. - Compute the HMAC-SHA256 of the result, using your client
secret_keyas the key. It is the same key that signs your Data Webhooks.
Data Webhooks use the same rule, with datetime_string from the metadata in place of action_datetime.
The notification_version field in the body identifies the notice format. Version 1 notices do not include it. Version 2 notices carry the value 2, and this is their format:
user_idalways arrives as the identifier you gave the user. Some sources used to add the first eight characters of yourclient_uuidto it, for exampleuser-001-11111111; now it arrives asuser-001.action_datetimeis in UTC, in ISO 8601 format, ending inZ.levelis lowercase:info,warn, orerror.messageis always text.
{
"client_uuid": "11111111-2222-4333-8444-555555555555",
"user_id": "user-001",
"data_source": "garmin",
"action": "user_connected",
"level": "info",
"message": "A new user has been successfully linked",
"action_datetime": "2026-10-19T10:00:00.000000Z",
"environment": "sandbox",
"scopes": null,
"notification_version": 2
}
Verify the Signature in Your Code
import hashlib
import hmac
def is_valid(body: dict, received_hash: str | None, secret_key: str) -> bool:
if not received_hash:
return False # No X-ROOK-HASH header: there is nothing to verify.
# The "Send test" sample has no action_datetime: it is signed with metadata.datetime.
action_datetime = body.get("action_datetime") or (body.get("metadata") or {}).get("datetime")
message = "".join([
body.get("client_uuid") or "",
body.get("user_id") or "",
action_datetime or "",
])
expected = hmac.new(
secret_key.encode(), message.encode(), hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, received_hash)
const crypto = require("crypto");
function isValid(body, receivedHash, secretKey) {
if (!receivedHash) {
return false; // No X-ROOK-HASH header: there is nothing to verify.
}
// The "Send test" sample has no action_datetime: it is signed with metadata.datetime.
const actionDatetime = body.action_datetime ?? body.metadata?.datetime;
const message = [body.client_uuid, body.user_id, actionDatetime]
.map((value) => value ?? "")
.join("");
const expected = crypto
.createHmac("sha256", secretKey)
.update(message)
.digest("hex");
return (
expected.length === receivedHash.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(receivedHash))
);
}
Compare the digests with a constant-time function and reject the notice when the comparison fails.
Test Your Code with a Known Example
These values are fake and only meant for testing your code:
| Field | Value |
|---|---|
secret_key | test-secret-not-real |
client_uuid | 11111111-2222-4333-8444-555555555555 |
user_id | user-001 |
action_datetime | 2026-10-19T10:00:00.000000Z |
The string to sign is 11111111-2222-4333-8444-555555555555user-0012026-10-19T10:00:00.000000Z.
The expected X-ROOK-HASH is fbd3610e9e8249696581ca0d500cde366586fbb3013a297598745f0720d6c577.
Limitations
- The signature covers
client_uuid,user_id, andaction_datetime. It does not cover the rest of the body. - Read the three values from the parsed body as received. Do not re-serialize or reformat the body first.
- The Send test button in the portal sends a sample in the version your Notification Webhook is on. On version 2, the sample has the version 2 format, with
action_datetime, and it is signed the way a real notice is. On version 1, the sample is signed with the same method, but it has noaction_datetime: it carriesmetadata.datetimeand that value is the one it is signed with. The code above already falls back to it, so both samples verify as expected. - Keep the secret key out of logs and source control.
Notices You Can Receive
Every version 2 notice has the fields shown in the example above. This table lists each action value, its level, when ROOK sends it, its extra fields, and the data sources it is available for.
Version 1 does not send user_shared_account_detected, user_pre_existing_data_delivered or user_data_sync_stalled, and its notices do not carry scopes, cause or other_user_id.
action | level | Sent when | Extra fields | Available for |
|---|---|---|---|---|
user_created | info | A user is created in your account. | None | All |
user_connected | info | A user connects a data source. | scopes, connection_type | Garmin, Oura, Polar, Strava, Whoop, Withings, Android, Apple Health, Health Connect and Samsung Health |
user_disconnected | info | A user disconnects a data source. | None | Garmin, Oura, Polar, Strava, Whoop, Withings, Google Health, Android, Apple Health, Health Connect and Samsung Health |
user_permission_failed | warn | ROOK cannot access a user's data because of an authorization problem. | cause | Oura, Polar, Strava and Whoop |
user_data_extraction | warn | ROOK could not retrieve a user's data after several attempts. | failed_attempts | Garmin, Oura, Polar, Strava, Whoop and Withings |
webhook_send_data | error | ROOK could not reach your webhook endpoint. | None. It has no user_id, and data_source holds the data structure (for example physical_summary) instead of the data source. | All |
user_shared_account_detected | info | Two users of your account are connected with the same data source account. | other_user_id | Garmin, Oura, Polar, Strava, Whoop and Withings |
user_pre_existing_data_delivered | info | ROOK delivered a user's pre-existing data to your Data Webhook. | None | Garmin, Oura, Polar, Whoop and Withings |
user_data_sync_stalled | warn | No data has arrived for a user from one of their data sources for more than 7 days. | None | Apple Health, Fitbit, Garmin, Google Health, Health Connect, Oura, Polar, Samsung Health, Whoop and Withings |
user_deleted, permission_request_launched, background_sync_started, data_transmission_failed and app_opened | Set by the SDK | Your app reports them through the mobile SDK. ROOK does not verify them. | None | Apple Health, Health Connect and Samsung Health |
Notice Fields and Repeated Notices
In version 2, some notices carry extra fields, besides the ones in the example above. Version 1 does not send them:
user_connectedcarriesscopes: the permissions the user granted, with ROOK's names. Oura, Strava, Whoop and Withings send them; for every other data sourcescopesisnull. Thegranted_scopesfield of the API reference is read from the permissions that ROOK stores, so it covers more data sources than this notice. It also carriesconnection_typefor the mobile data sources (Android, Apple Health, Health Connect and Samsung Health):initialwhen the user connects for the first time, andreconnectwhen the user connects again. ROOK's scope names are:activity,blood_glucose,blood_pressure,cardio_fitness,ecg,heart_rate,location,nutrition,oxygen_saturation,profile,respiratory_rate,sleep,temperatureandweight.user_permission_failedmay carrycause:token_expired(the access token is no longer accepted),permission_missing(the user did not grant a permission), orpermission_revoked(the user revoked the permission). A data source may send only some of them.user_shared_account_detectedcarriesother_user_id: theuser_idof another user of your account who is connected with the same data source account. ROOK sends it once for each pair of users, to the user who connected last, and never includes the data source's own identifier. It is available for Garmin, Oura, Polar, Whoop, Withings and Strava.user_pre_existing_data_deliveredis sent once ROOK has delivered a user's pre-existing data to your Data Webhook. If that data cannot be delivered, the notice is not sent. It is available for Garmin, Oura, Polar, Whoop and Withings.user_data_sync_stalledis sent when no data has arrived for a user from one of their data sources for more than 7 days. It is available for Apple Health, Fitbit, Garmin, Google Health, Health Connect, Oura, Polar, Samsung Health, Whoop and Withings. ROOK checks once a day. The notice haslevelset towarn, carries no extra fields, and does not say why the data stopped. A user who connected less than 14 days ago is not reported, to leave room for the pre-existing data.
Example of a user_data_sync_stalled notice:
{
"client_uuid": "11111111-2222-4333-8444-555555555555",
"user_id": "user-001",
"data_source": "garmin",
"action": "user_data_sync_stalled",
"level": "warn",
"message": "No data has been received for this user and data source in more than 7 days.",
"action_datetime": "2026-10-19T06:43:00.000000Z",
"environment": "sandbox",
"notification_version": 2
}
In version 2, ROOK sends the same notice for the same user, data source, and cause at most once every 24 hours. If the problem continues after those 24 hours, you receive the notice again. The user_data_sync_stalled notice is held for 7 days instead, so while the silence lasts it arrives at most once every 7 days. Connecting the user again starts over. In version 1, every notice is sent as it arrives.