> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/health-and-fitness-api/managing-user-health-data/receiving-data-updates.md).
# Receiving health data updates (events)
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:
1. [**Health Data Events**](#data-events)**:** sent to your destination when new data is available on the user's account.
2. [**How to test your Destination**](https://dashboard.tryterra.co/dashboard/generate)**:** Terra sends [events](/introduction/core-concepts.md#event) to your [destination](/introduction/core-concepts.md#destination), learn how to test this.
3. [**Common errors and troubleshooting**](#common-errors-and-troubleshooting)**:** when not receiving expected data.
{% hint style="success" %}
### **Prerequisites**
In order to receive Data as **Events**, you'll need to:
1. [**API Key**:](https://dashboard.tryterra.co/) Obtain your API Key from your Terra Dashboard
2. [**Destination Configured**:](/health-and-fitness-api/integration-setup.md#set-up-your-data-sources-and-destinations) Set up a data destination where Terra will send event and data updates.
3. [**Data Sources Enabled**:](/health-and-fitness-api/integration-setup.md#set-up-your-data-sources-and-destinations) Enable the specific data sources your app requires (e.g., oura, garmin, etc).
4. **Connected at least a user.**
1. If not, then no worries, you can use the [Payload Simulator](https://dashboard.tryterra.co/dashboard/generate) to test sending data to your destination!
2. However, make sure to familiarize yourself with [Authentication Events](broken://pages/j6nBtfGYuTZY8Spl4Abk).
{% endhint %}
***
## 1. Types of Health Data Events
Whenever a [User](/reference/health-and-fitness-api/core-concepts.md#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:
(1) Activity: A tracked workout, with a defined start and end time.
Unique identifier (per [User](/reference/health-and-fitness-api/core-concepts.md#user)): `metadata.summary_id`
For example, an [End User](https://github.com/tryterra/gitbook-docs/blob/master/health-and-fitness-api/broken-reference/README.md) pressing **"start run"** on their watch, going for a 5k run, and pressing **"end run"**
See [GET activity](/reference/health-and-fitness-api/readme.md#activity) for the full Schema & descriptions of each field
(2) Daily: the total daily summary of the user's activity up to the point in time of the event
Unique identifier (per [User](/reference/health-and-fitness-api/core-concepts.md#user)): `metadata.start_time`
This can be the cumulative number of steps, calories burned, etc. `daily` payloads are always relevant to a given 24 hour period, defined by the `start_time` and `end_time` of the `metadata` key. When parsing, only consider the **date** part of the field, and ignore the time.
See [GET daily](/reference/health-and-fitness-api/readme.md#daily) for the full Schema & descriptions of each field
(3) Body: the recorded body metrics for the user for a given day
Unique identifier (per [User](/reference/health-and-fitness-api/core-concepts.md#user)): `metadata.start_time`
`body` payloads are always relevant to a given 24 hour period, defined by the `start_time` and `end_time` of the `metadata` key.
See [GET body](/reference/health-and-fitness-api/readme.md#body) for the full Schema & descriptions of each field
(4) Sleep: a tracked sleep session, with a defined start and end time.
Unique identifier (per [User](/reference/health-and-fitness-api/core-concepts.md#user)): `metadata.summary_id`
This can include time spent in bed while awake, if recorded by the wearable.
See [GET sleep](/reference/health-and-fitness-api/readme.md#sleep) for the full Schema, example, & descriptions of each field
(5) Menstruation: menstrual metrics for the user for a given day
Unique identifier (per [User](/reference/health-and-fitness-api/core-concepts.md#user)): `metadata.start_time`
E.g. the phase they're currently on, their blood flow for the day, etc. `menstruation` payloads are always relevant to a given 24 hour period, defined by the `start_time` and `end_time` of the `metadata` key.
See [GET menstruation](/reference/health-and-fitness-api/readme.md#menstruation) for the full Schema, example, & descriptions of each field
(6) Planned Workout: a step by step workout plan for the end user
Unique identifier (per [User](/reference/health-and-fitness-api/core-concepts.md#user)): `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 [here](/health-and-fitness-api/managing-user-health-data/write-data.md#writing-planned-workouts) for more info
You can find more details about these **Data Events** in the [Event Type](/reference/health-and-fitness-api/event-types.md) reference.
You can find all your received events (payloads) in:
* Your [Terra Dashboard > Payload History](https://dashboard.tryterra.co/dashboard/debug).
{% hint style="warning" %}
**Overwriting/Updating data**
* Whenever you receive an event for a [User](/reference/health-and-fitness-api/core-concepts.md#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.
{% endhint %}
#### **Example of a Health & Fitness Payload**
Data Events will take the following form:
{% code title="ActivityPayload.json" lineNumbers="true" %}
```json
{
"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"
}
```
{% endcode %}
## 2. How to test your Destination?
For testing out the different event types mentioned above, you may also use [the payload simulator](https://dashboard.tryterra.co/dashboard/generate) in the Terra Dashboard. See the tutorial below for a step by step guide.
{% embed url="" %}
## 3. FAQ: Common errors & troubleshooting
Found in [**Debugging FAQ.**](https://app.gitbook.com/o/FSHKsjH8Q1Ejnax0ajY6/s/VGMJVuZnZyOtvV4b53cY/~/changes/96/debugging-faq)
***
## ✅ Checklist
{% hint style="success" %}
### Receiving data Updates
1. **Set-up**: Have you tested that your destination can receive data payloads from Terra?
2. **Connect a User**: Have you connect a user via Terra? Have you received an Authentication Event?
3. **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**](https://app.gitbook.com/o/FSHKsjH8Q1Ejnax0ajY6/s/VGMJVuZnZyOtvV4b53cY/~/changes/96/debugging-faq) to ensure the user's data is synced properly.
{% endhint %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.tryterra.co/health-and-fitness-api/managing-user-health-data/receiving-data-updates.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.