ROOK delivers health data through webhooks for real-time updates. We 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 as shown in our API Reference.
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. Data Structures: we divide the data as shown 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.
You can see real examples in this github repository.
3. 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.
4. 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.