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
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:
Health Data Events: sent to your destination when new data is available on the user's account.
How to test your Destination: Terra sends events to your destination, learn how to test this.
Common errors and troubleshooting: when not receiving expected data.
Prerequisites
In order to receive Data as Events, you'll need to:
API Key: Obtain your API Key from your Terra Dashboard
Destination Configured: Set up a data destination where Terra will send event and data updates.
Data Sources Enabled: 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 Payload Simulator to test sending data to your destination!
However, make sure to familiarize yourself with Authentication Events.
1. Types of Health Data Events
Whenever a User has new data available on the respective platform they use, Terra will send a Data Event to your Data Destination.
Data Events fall under one of the following categories:
You can find more details about these Data Events in the Event Type reference.
You can find all your received events (payloads) in:
Overwriting/Updating data
Whenever you receive an event for a User 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.
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.
Example of a Health & Fitness Payload
Data Events will take the following form:
{
"type": "activity",
"data": [
{
"metadata": {
"type": 45,
"start_time": "2024-10-03T18:17:45.000000+08:00",
"city": null,
"name": "MEDITATION",
"state": null,
"upload_type": 1,
"country": null,
"summary_id": "f09554ca56fde426de5d7f9c34fc0e1e3ff015c2ae253b39",
"end_time": "2024-10-03T18:38:39.000000+08:00"
},
..... ommitted for brevity
}
],
"user": {
"reference_id": "2397",
"active": true,
"user_id": "9d5dc9eb-3e02-4b37-9a7b-b14b5a5a2b93",
"last_webhook_update": "2024-10-03T11:13:43.360227+00:00",
"created_at": null,
"scopes": "fitness.sleep.read,fitness.body.read,fitness.body_temperature.read,fitness.activity.read,fitness.blood_pressure.read,fitness.location.read,calendar.settings.readonly,fitness.reproductive_health.read,userinfo.email,user.birthday.read,user.gender.read,fitness.oxygen_saturation.read,fitness.heart_rate.read,userinfo.profile,fitness.nutrition.read,fitness.blood_glucose.read",
"provider": "GOOGLE"
},
"version": "2022-03-16"
}
2. How to test your Destination?
For testing out the different event types mentioned above, you may also use the payload simulator in the Terra Dashboard. See the tutorial below for a step by step guide.
3. FAQ: Common errors & troubleshooting
Found in Debugging FAQ.
✅ Checklist
Receiving data Updates
Set-up: Have you tested that your destination can receive data payloads from Terra?
Connect a User: Have you connect a user via Terra? Have you received an Authentication Event?
Receiving Data: After completing an event (e.g. activity), did you receive a Data Event "Activity"?
If you didn't receive an expected payload after a long time, please refer to our Debugging FAQ to ensure the user's data is synced properly.
Last updated
Was this helpful?