Skip to main content

Data Delivery

Summary

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:

  1. ROOK Data Webhooks: Provides real-time delivery of new events or summaries.
  2. 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​

  1. Security:

    • Use the X-ROOK-HASH header 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.
  2. 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.

Setting Up Webhooks​

  1. Prepare the Webhook URL:

    • Ensure the URL can accept HTTP POST requests and process incoming JSON payloads.
  2. 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.
  3. Response Validation:

    • Respond with one of the following status codes to confirm receipt:
      • 200 OK
      • 201 Created
      • 202 Accepted
    • Invalid responses trigger retry attempts.

Testing Tip: Use tools like Webhook.site during development to test webhook payloads.

tip

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

Important Considerations When Using the ROOK API​

  1. Not Real-Time:

    • The API does not provide real-time data. Webhooks should be used for immediate notifications of new data.
  2. 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.
  3. 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.
  4. Developer Resources:

    • Access the full API reference and download the OpenAPI specification at API Reference.
warning

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-HASH signature, without notification_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-HASH signature, and the new notices user_shared_account_detected, user_pre_existing_data_delivered and user_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:

  1. Take the client_uuid, user_id, and action_datetime values from the body you received.
  2. Concatenate them in that order, with no separator.
  3. Use an empty string for any of the three that is absent or null.
  4. Compute the HMAC-SHA256 of the result, using your client secret_key as 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_id always arrives as the identifier you gave the user. Some sources used to add the first eight characters of your client_uuid to it, for example user-001-11111111; now it arrives as user-001.
  • action_datetime is in UTC, in ISO 8601 format, ending in Z.
  • level is lowercase: info, warn, or error.
  • message is 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:

FieldValue
secret_keytest-secret-not-real
client_uuid11111111-2222-4333-8444-555555555555
user_iduser-001
action_datetime2026-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, and action_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 no action_datetime: it carries metadata.datetime and 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.

actionlevelSent whenExtra fieldsAvailable for
user_createdinfoA user is created in your account.NoneAll
user_connectedinfoA user connects a data source.scopes, connection_typeGarmin, Oura, Polar, Strava, Whoop, Withings, Android, Apple Health, Health Connect and Samsung Health
user_disconnectedinfoA user disconnects a data source.NoneGarmin, Oura, Polar, Strava, Whoop, Withings, Google Health, Android, Apple Health, Health Connect and Samsung Health
user_permission_failedwarnROOK cannot access a user's data because of an authorization problem.causeOura, Polar, Strava and Whoop
user_data_extractionwarnROOK could not retrieve a user's data after several attempts.failed_attemptsGarmin, Oura, Polar, Strava, Whoop and Withings
webhook_send_dataerrorROOK 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_detectedinfoTwo users of your account are connected with the same data source account.other_user_idGarmin, Oura, Polar, Strava, Whoop and Withings
user_pre_existing_data_deliveredinfoROOK delivered a user's pre-existing data to your Data Webhook.NoneGarmin, Oura, Polar, Whoop and Withings
user_data_sync_stalledwarnNo data has arrived for a user from one of their data sources for more than 7 days.NoneApple 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_openedSet by the SDKYour app reports them through the mobile SDK. ROOK does not verify them.NoneApple 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_connected carries scopes: the permissions the user granted, with ROOK's names. Oura, Strava, Whoop and Withings send them; for every other data source scopes is null. The granted_scopes field of the API reference is read from the permissions that ROOK stores, so it covers more data sources than this notice. It also carries connection_type for the mobile data sources (Android, Apple Health, Health Connect and Samsung Health): initial when the user connects for the first time, and reconnect when 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, temperature and weight.
  • user_permission_failed may carry cause: token_expired (the access token is no longer accepted), permission_missing (the user did not grant a permission), or permission_revoked (the user revoked the permission). A data source may send only some of them.
  • user_shared_account_detected carries other_user_id: the user_id of 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_delivered is 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_stalled is 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 has level set to warn, 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.