Skip to main content

Data Delivery

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.

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, 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.

  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 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 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: Use tools like Webhook.site during development to 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 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/.

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.