Skip to main content

Data Consumption

ROOK provides three methods for accessing and utilizing the supplied health data: API queries, Software Development Kits (SDKs), and webhook functionality. This guide explores how to effectively manage health data and notifications using these resources.

Webhooks​

Webhooks notify you when new health data events or summaries are available for your users.

note

To ensure the authenticity of information received via webhooks, we send an HMAC header code named X-ROOK-HASH. Learn more here.

Notifications Endpoint Registration​

Upon creating your account as a client, you will need to provide your Rest API endpoint where you want to receive notifications. If your account is already created, you can contact ROOK support to register or update your endpoint.

Notifications Endpoint Characteristics​

The endpoint must:

  • Use the POST method
  • Not require an Authorization header
  • Respond with 200, 201, or 202 when successfully receiving our notification

Notifications Triggers​

Notifications are sent when:

  • New events are detected for a user:
    • Notification speed depends on the health data source technology. We:
      • Send fast notifications when the health data source notifies us via webhooks.
      • Poll for new health data every hour from sources without webhooks and notify you if new data is detected.
  • Daily summaries are ready: At 0:00 UTC, we send the previous day's summaries for your users.

Notifications Content​

The notification content varies based on the health data pillar that triggered the notification. The payload will include data from one of the three health data pillars, and it could be either a summary or an event, as defined in the health data structure.

For detailed data delivery information, visit our API reference.

API​

Our ROOKConnect API allows you to request your user's health data on demand.

note

To test the API, you will need your client credentials. Please contact us to obtain them.

To make a request, you will need:

  • An api_url
  • A client_uuid
  • A secret_key
  • Basic authentication: Use the client_uuid and secret_key as the username and password, respectively.
  • A user_id
  • The health pillar you want to retrieve information from (Sleep, Physical and Body)
  • The data type you are requesting (Summary, Event)
  • The date of the data you want to obtain
note
  • In the Sandbox environment, you have two options:
    • Use a real user_id of a user with a data source that generates health data.
    • Alternatively, use demoUserId as the user_id value to receive demo data. Note that this option is only valid in the Sandbox environment.
  • In the Production environment, you must use the user_id of your actual users.

Frequency​

ROOK collects, processes, and delivers data in a timely and reliable manner. The frequency of data collection depends on the data type.

Events​

Events are collected instantly as users complete activities in their data sources. The data is then imported, processed, and notified to customers through webhooks or endpoints.

Summaries​

Summaries are processed individually for each pillar once a day. This processing schedule allows data collected throughout the day to be imported and notified to customers at a set time, ensuring all users can access their data at 11:00 AM according to their time zone.