Skip to main content

QuickStart Guide

Description​

This QuickStart guide presents the essential steps to collect, process, and deliver health data using ROOK. Learn how to configure webhooks for real-time notifications, integrate mobile and API-based sources, and ensure a smooth Production deployment through ROOK APIs and SDKs.

Prerequisites​

Team Requirements for ROOK Integration​

To successfully integrate ROOK, your organization needs the following teams based on your APP needs:

Backend Team​

  • Receive Data: Build an API to receive health data sent by ROOK.
  • Data Storage and Processing: Store the data securely for further processing.
  • Serve Your APP: Develop an API to serve your end-user APP.

Frontend Team (Optional)​

  • Custom Connections Pages: Create a user-facing page that allows users to authorize access to their health data.
  • Dashboards: Build dashboards to present health data clearly and actionably.

Mobile Team (If Needed)​

ROOK integrates with two types of data sources: API-Based and Mobile-Based. Learn more about supported sources in Data Sources.

  • If Interested in Mobile-Based Data Sources:
    • Use the ROOK Extraction APP: A ready-to-use APP to collect data from Apple Health and Health Connect.
    • Develop a Custom Mobile APP: Integrate ROOK SDKs for Apple Health and Health Connect.

Data Sources and Testing​

Before integration, it is recommended to:

  • Obtain Devices or Accounts for the selected data sources.
  • Ensure Test Users Have Existing Data: Users should have pre-existing health data available.
    • ROOK supports the extraction of pre-existing data. See Pre-existing Data for more information.

  1. Data Reception:

    • Create an endpoint to receive webhook data from ROOK.

  2. Data Storage:

    • Store data securely for further analysis.

  3. Backend Development:

    • Receive, store, process, and serve the data to your APP.

  4. Frontend or APP Integration:

    • Integrate ROOK SDKs or use the ROOK Extraction APP for mobile-based data sources.
    • Use backend APIs to serve data to web or mobile APPs.

Integration Steps​

The integration process consists of three phases: account creation, Sandbox testing, and Production deployment.

Step 1: Create Your Account​

The ROOK Portal is the central hub for integration.

Once registered, you can:

  • Configure data sources and webhooks.
  • Monitor integration performance.

Note: Credentials for Production are generated after completing Sandbox validation.

Required Information​

  • Email and password.
  • Company name, sector, and optional logo.
  • Project lead's name and role.
  • Estimated number of users.

ROOK Portal Dashboard

Step 2: Test in Sandbox Environment​

The Sandbox environment allows testing without impacting Production data.

2.1: Generate Credentials​

Navigate to the Settings/Credentials section to generate your Sandbox Client UUID and Secret Key.

info
  • The Secret Key appears only once. Store it securely.
  • Sandbox and Production credentials are separate.

Credentials

2.2: Test a Ready-to-Use Connections Page (Sandbox Only)​

ROOK provides a Connections Page to quickly simulate how user authorization would appear during integration.
This page is intended solely for quick sandbox testing and should not be used in production environments.

Use the Sandbox Connections Page to validate the user authorization flow visually and quickly during testing.

Clients must build their own custom connections page or app view for production environments using the appropriate endpoints, as the sandbox Connections Page is not intended for live user authorization.

Connection Page

Optional: Configuring Data Sources in the Portal

In the ROOK Portal, clients can:

  • Activate or deactivate visible data sources.
  • Customize basic visual elements, such as colors, to simulate branding during the authorization process.

This configuration is intended only for the sandbox Connections Page and does not affect authorization flows.

Important Considerations:

  • The Connections Page uses an older endpoint /api/v1/client_uuid/{client_uuid}/user_id/{user_id}/data_sources/authorizers, which retrieves all data sources.
  • This endpoint is deprecated and is not recommended for production use.
  • Configuring the list of data sources in the Portal only affects the display on the sandbox Connections Page; it does not impact the actual authorization process.
  • In production, clients must use the individual data source authorizer endpoint, which allows direct authorization without needing prior configuration in the Portal.
Optional: Building a Custom Connections Page with the Authorizer Endpoint

Although the Sandbox Connections Page is designed for rapid testing, clients also have the option to start building a real custom authorization flow from the beginning.

By using the individual data source authorizer endpoint, clients can:

  • Request authorization URLs dynamically for each data source.
  • Fully control the branding and behavior of the authorization process.
  • Simulate a production-grade user flow even during sandbox testing.

This approach is optional during quickstart testing but is recommended for clients who prefer to validate the complete production integration as early as possible.

2.3: Set Up Webhooks​

Configure the data webhook to receive real-time extracted health data.

  1. Provide a secure POST URL.
  2. Test payloads using tools like Webhook.site.
note
  • Webhooks are the primary mechanism through which clients receive extracted user health data from ROOK.
  • The API is available for specific queries and debugging purposes, but it is not intended for continuous data retrieval. See Data Delivery.
Optional: Notification Webhook for Integration Monitoring

ROOK also provides a Notification Webhook that sends real-time alerts related to integration events.
Unlike the data webhook, this notification webhook does not deliver health metrics. It is intended to help monitor and troubleshoot events such as:

  • New user creation
  • Data source connections or disconnections
  • Failed data extractions

Setting up the Notification Webhook is optional and generally recommended for clients preparing for production deployments.

For configuration guidance, refer to the Data Delivery section.

Webhook

2.4: Connect Users​

Users must authorize ROOK to access their health data through either API-based or mobile-based sources.

  • API-Based Sources:
    For API-based sources such as Fitbit, Garmin, or Oura, ROOK presents an authorization view where users grant access to their health data. After authorization, ROOK establishes the connection and begins extracting the user's data.

    • Use the Sandbox Connections Page for quick testing purposes only.
    • For Production, clients must build their own connections page (for web) or an app view (for mobile) using the individual data source authorizer endpoint. This approach allows for full branding control and does not depend on prior portal configurations.

  • Mobile-Based Sources:
    For mobile-based sources such as Apple Health and Health Connect:

    • Clients can develop their own APP by integrating ROOK SDKs, which handle both the authorization and the data extraction processes.
    • Alternatively, clients can use the ROOK Extraction APP, which is ready-to-use and automatically manages user authorization and data synchronization.

Connect Users

2.5: Validate Data Flow​

Validate the correct flow of health data after user authorization and connection.

  • Monitor Incoming Webhooks:
    After users authorize ROOK to access their health data, monitor the configured webhooks to ensure that health metrics are being delivered correctly. This is the recommended method for validating that data from authorized users is flowing without issues in near real time.

  • Query the API (Optional for Debugging):
    Clients can also perform on-demand queries to the ROOK API to retrieve specific user health data. However, using the API as the main method for continuous data retrieval is not recommended for Production environments. Webhooks provide a more reliable and scalable delivery mechanism.

  • Validate Schemas:
    Use the reference documentation at Data Types to ensure that incoming payloads match the expected structures for summaries and events.

Step 3: Transition to Production​

After successful Sandbox testing, transition to the Production environment. Most steps are similar, with a few differences specifically for credential generation and configuration.

3.1: Request Production Enablement​

Before accessing the Production environment, contact ROOK Support to request Production enablement. This step ensures all configurations are verified before proceeding.

3.2: Configure Production Environment​

Follow the same process used in Sandbox:

  • Generate Production credentials in the ROOK Portal.
  • Configure Production data sources, if necessary, for visibility in the portal.
Important: About Configuring Data Sources

Configuring data sources in Production is generally unnecessary:

  • The Sandbox Connections Page is not available in the Production environment.
  • The previous /data_sources/authorizers endpoint is deprecated and should not be used for Production flows.
  • In Production, clients must use the individual data source authorizer endpoint, which does not require configuring available data sources through the ROOK Portal.

As a result, configuring data sources in Production does not impact authorization workflows.

  • Set up Production webhooks to receive live health data.
Note: Data Flow Consistency

Data flows and webhook payloads follow the same structure as in Sandbox. However, Production data reflects live user activity and must be handled according to your platform’s security and processing standards.

3.3: Connect Production Users​

  • API-Based Sources:
    As in Sandbox, users must authorize ROOK to access their health data. However, for Production, it is mandatory to build a custom Connections Page or mobile APP view using the individual data source authorizer endpoint.
    Using the Sandbox Connections Page is not allowed in Production environments.

  • Mobile-Based Sources:
    Either integrate the ROOK SDKs into your mobile APP or deploy the ROOK Extraction APP to manage mobile-based data collection and authorization.

3.4: Start Receiving Live Data​

After connecting Production users:

  • Monitor incoming data through configured Production webhooks.
  • Use the ROOK API for specific queries when necessary (for example, for data verification or debugging).
  • Refer to Data Types to validate the structure and consistency of incoming payloads.

Conclusion​

ROOK's QuickStart Guide provides a clear foundation for integration:

  1. Create an account on the ROOK Portal.
  2. Test in Sandbox to validate workflows.
  3. Transition to Production for live data delivery.

To continue building a full integration, explore the following topics for advanced setup: