Skip to main content

Data Delivery

ROOK offers 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.

Data Delivery Mechanisms​

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.

Types of Webhooks​

  1. Data Webhooks:

    • Deliver health data (e.g., events and summaries) in real time.
    • Cover Sleep, Physical, and Body health pillars.
    • Triggered when:
      • New events occur (e.g., step counts, heart rate measurements).
      • Summaries are generated (e.g., daily activity or sleep reports).
    • Summaries are extracted and delivered based on user-specific time zones for timely updates. Refer to the Data Extraction Section for more details.
    • Payloads align with the JSON schemas used in the ROOK API. Refer to the API Reference.
    • Setup: Configured directly in the ROOK Portal.

  2. Notification Webhooks:

    • Provide updates about integration-specific actions, such as:
      • User creation or deletion.
      • Data source connections or disconnections.
      • Failed data retrieval attempts.
    • Setup: Requires manual configuration. Contact ROOK Support.
    • Learn more in the Notification Webhook documentation.

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 intervals of:
      • 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 about 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 the "Webhooks" section.
    • Separate configurations are required for Sandbox and Production environments.
    • Notification Webhooks require contacting ROOK Support for manual setup.

  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: During development, tools like Webhook.site can help test webhook payloads.

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 the recommended method 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 Notes About 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 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 not make API requests to ROOK whenever users access their data.
    • Instead:
      • Build a backend and database to store the data received from ROOK.
      • Applications should query the backend, not ROOK’s API, for user data.
    • Using the API as a primary data source for end-user applications violates usage policies.

  4. Developer Resources:

    • Access the full API reference and download the OpenAPI specification for seamless integration. Learn more at /api/.

Shared Features Across Webhooks and API​

ROOK offers several configurable features that apply to both APIs and webhooks:

  1. Granular Data Control:

    • Configure whether granular data (e.g., detailed metrics like heart rate or step-level activity) is included in summaries and events.
    • Clients can request this feature by contacting ROOK Support. Learn more about Granular Data Exclusion.

  2. Time Zone Support:

    • Summaries are extracted based on the user’s local time zone to ensure relevance.
    • Default extraction times:
      • Physical summaries: 00:01 (user's local time).
      • Sleep summaries: 12:00 (user's local time).
    • Clients can request custom extraction times. Learn more in How Does the Timezone Feature Work?.

  3. Duplicate Handling:

    • If a summary or event is updated (e.g., additional data is synced), ROOK sends the updated information with a new document_version.

  4. Retry Extractions:

    • For summaries not available at the scheduled extraction time, ROOK retries extraction multiple times per day for up to 30 days.
    • Delayed extractions may affect delivery times.

Comparing ROOK API and Data Webhooks​

FeatureROOK APIROOK Data Webhooks
Use CaseOn-demand data queriesReal-time data delivery
Data FormatJSON (aligned with webhooks)JSON (aligned with API)
Real-Time UpdatesNot supported (polling required)Supported
Retry MechanismNot applicableIncluded
SetupRequires credentials and endpointConfigured in portal
Environment-Specific AccessYesYes

Recommendations​

  • Use Data Webhooks for real-time updates and proactive notifications.
  • Use the ROOK API for specific, on-demand queries or additional data flexibility.

For further assistance, contact ROOK Support.