Receiving health data updates (events)
Learn how to receive data update events to your app as soon as the user's data syncs to the cloud
Last updated
Was this helpful?
Learn how to receive data update events to your app as soon as the user's data syncs to the cloud
Last updated
Was this helpful?
Terra API simplifies health & fitness data syncing: once you connect a user, Terra automatically manages token refreshes, authentication updates, and delivers all health and fitness data directly to your Webhook/DB as soon as it’s available.
Requesting data is not required unless you need to backfill historical data, to debug, or as a fallback. This lets you focus on your app while Terra handles the data flow and reliability.
In this section, you will learn about:
: sent to your destination when new data is available on the user's account.
: Terra sends to your , learn how to test this.
: when not receiving expected data.
In order to receive Data as Events, you'll need to:
Obtain your API Key from your Terra Dashboard
Set up a data destination where Terra will send event and data updates.
Enable the specific data sources your app requires (e.g., oura, garmin, etc).
Connected at least a user.
If not, then no worries, you can use the to test sending data to your destination!
However, make sure to familiarize yourself with Authentication Events.
Data Events fall under one of the following categories:
You can find all your received events (payloads) in:
This means you should always overwrite data stored on your end with the most up-to-date version.
Depending on the event type, use the unique identifier for each payload to overwrite data appropriately upon receiving an update (e.g. metadata.start_date
, metadata.summary_id
, etc). These unique identifiers are found in the category descriptions listed above.
Data Events will take the following form:
Whenever a has new data available on the respective platform they use, Terra will send a Data Event to your Data Destination.
Unique identifier (per ): metadata.summary_id
For example, an pressing "start run" on their watch, going for a 5k run, and pressing "end run"
See for the full Schema & descriptions of each field
Unique identifier (per ): metadata.start_time
See for the full Schema & descriptions of each field
Unique identifier (per ): metadata.start_time
See for the full Schema & descriptions of each field
Unique identifier (per ): metadata.summary_id
See for the full Schema, example, & descriptions of each field
Unique identifier (per ): metadata.start_time
See for the full Schema, example, & descriptions of each field
You can find more details about these Data Events in the reference.
Your .
Whenever you receive an event for a which constitutes a duplicate, based on the data type's unique identifier (detailed in each section below), the received data will always be a superset of any previous data received.
For testing out the different event types mentioned above, you may also use in the Terra Dashboard. See the tutorial below for a step by step guide.
Found in
If you didn't receive an expected payload after a long time, please refer to our to ensure the user's data is synced properly.
Unique identifier (per ): metadata.summary_id
A planned workout, with a defined set of steps/reps/sets to be followed. For example, 15 min running at 7:00 pace, followed by 3x repetitions of 100m sprints with 45s jog at 8:00 min pace in between. See for more info