ROOK delivers health data through webhooks for real-time updates and through an API for on-demand queries. Both methods use consistent JSON schemas, ensuring seamless integration across systems. ROOK organizes health data into three pillars: Physical Health, Body Health, and Sleep Health. Data is further divided into Summaries, which are daily aggregated metrics, and Events, which are detailed records of specific activities or measurements.
Here's how data is structured and delivered, including examples:
1. Data Webhooks:
Real-time delivery: Webhooks are the preferred method for receiving real-time data updates from ROOK, eliminating the need for constant polling.
Data Types: Data Webhooks deliver health data, such as events and summaries, in real time, covering the Sleep, Physical, and Body health pillars.
Triggers: Webhooks are triggered when new events occur (e.g., step counts, heart rate measurements) or summaries are generated (e.g., daily activity or sleep reports).
Example: A webhook is triggered when a user completes a workout, delivering the workout's details.
Payloads: Payloads align with the JSON schemas used in the ROOK API.
Delivery: Data is delivered to a client-configured URL.
Security: The X-ROOK-HASH header is used for HMAC validation to ensure data authenticity.
Retry Logic: If delivery fails, retries are triggered 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.
2. ROOK API:
On-demand access: The ROOK API provides on-demand access to user health data, offering flexibility in querying specific metrics.
Consistent data format: API responses match webhook payloads, ensuring seamless integration.
Environment-specific URLs: There are separate URLs for the Sandbox and Production environments:
Sandbox: https://api.rook-connect.review
Production: https://api.rook-connect.com
Not real-time: The API does not provide real-time data; webhooks should be used for immediate notifications of new data.
Rate Limits: The API enforces rate limits based on subscription plans.
Typical limits:
Requests per minute: 60
Requests per day: 10,000
3. Data Structures we divide the data as showed here:
Physical Health Summary:
Delivered via webhook or API.
Includes daily aggregated metrics like total steps, calories burned, and activity time.
Example fields: client_uuid, user_id, version, document_version, data_structure (physical_summary), physical_health (containing summary with physical_summary, non_structured_data_array, and metadata).
Physical Health Event:
Delivered via webhook or API.
Includes detailed records of activities like a workout.
Example fields: client_uuid, user_id, version, document_version, auto_detected, data_structure (activity_event), physical_health (containing events with activity_event, non_structured_data_array, and metadata).
Sleep Health Summary:
Delivered via webhook or API.
Includes daily aggregated metrics like sleep duration and quality.
Example fields: client_uuid, user_id, version, document_version, data_structure (sleep_summary), sleep_health (containing summary with sleep_summary, non_structured_data_array, and metadata).
Body Health Summary:
Delivered via webhook or API.
Includes daily metrics like Body Mass Index (BMI).
Example fields: client_uuid, user_id, version, document_version, data_structure (body_summary), body_health (containing summary with body_summary, non_structured_data_array, and metadata).
Step Events
Delivered via webhook
Includes hourly step metrics.
Example fields: client_uuid, user_id, version, document_version, auto_detected, data_structure (steps_event), physical_health (containing events with steps_event, non_structured_data_array, and metadata, and physical_health with accumulated_steps_int).
ROOKScore 2.0:
Delivered via webhook.
Includes overall score and scores for each health pillar (Physical, Sleep, and Body).
Example fields: data_structure (health_score), version, document_version, user_id, client_uuid, health_score_data (containing metadata, overall_scores, physical_health_score, sleep_health_score, and body_health_score). Each health pillar contains a score_0_100_int field, along with scores for individual metrics.
4. Shared Features Across Webhooks and API
Granular Data Control: Clients can configure whether granular data is included in summaries and events.
Time Zone Support: Summaries are extracted based on the user’s local time zone.
Duplicate Handling: Updated information is sent with a new document_version.
Retry Extractions: For summaries not available at the scheduled extraction time, ROOK retries extraction multiple times per day for up to 30 days.
5. Data Processing:
ROOK processes data through harmonization, standardization, cleaning, and normalization before delivery.
Harmonization ensures consistency across data formats and units.
Standardization applies industry standards to ensure compatibility.
Cleaning eliminates inconsistencies and resolves duplicates.
Normalization adjusts data to a uniform scale and format.
By using these methods and adhering to consistent data structures, ROOK provides a comprehensive solution for accessing and integrating health data.