> 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/unified-api/receiving-data-updates.md).
# Health data events
Handle the data events Terra sends to your destination when a connected user's data syncs.
Once you connect a user, Terra refreshes their tokens, tracks authentication updates, and sends their health and fitness data to your destination as soon as it is available. You only need to request data to backfill history, to debug, or as a fallback.
## Before you begin
* Get your **API key** from the [Terra dashboard](https://dashboard.tryterra.co/).
* [Set up a destination](/destinations/setting-up-data-destinations.md) where Terra sends events.
* [Enable the data sources](/unified-api/setting-up-data-sources.md) your app needs (e.g., oura, garmin, etc).
* [Connect at least one user](/unified-api/authentication-flow.md), and [handle the auth event](/unified-api/authentication-flow.md#handle-the-auth-event). If you have no connected user yet, use the [Payload Simulator](https://dashboard.tryterra.co/dashboard/generate) to send test data to your destination.
## Data event types
When a connected [user](https://docs.tryterra.co/reference/health-and-fitness-api/core-concepts#user) has new data at their provider, Terra sends a data event to your [destination](/introduction/core-concepts.md#destinations). [Event delivery](/destinations/events.md) explains how Terra delivers and retries it.
Each data event has one of these types:
Activity: a tracked workout, with a defined start and end time.
Unique identifier (per [User](https://docs.tryterra.co/reference/health-and-fitness-api/core-concepts#user)): `metadata.summary_id`
For example, an [end user](https://docs.tryterra.co/reference/health-and-fitness-api/core-concepts#end-user) pressing **"start run"** on their watch, going for a 5k run, and pressing **"end run"**
See [GET activity](https://docs.tryterra.co/reference/health-and-fitness-api/readme#activity) for the full Schema & descriptions of each field
Daily: the total daily summary of the user's activity up to the point in time of the event
Unique identifier (per [User](https://docs.tryterra.co/reference/health-and-fitness-api/core-concepts#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](https://docs.tryterra.co/reference/health-and-fitness-api/readme#daily) for the full Schema & descriptions of each field
Body: the recorded body metrics for the user for a given day
Unique identifier (per [User](https://docs.tryterra.co/reference/health-and-fitness-api/core-concepts#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](https://docs.tryterra.co/reference/health-and-fitness-api/readme#body) for the full Schema & descriptions of each field
Sleep: a tracked sleep session, with a defined start and end time.
Unique identifier (per [User](https://docs.tryterra.co/reference/health-and-fitness-api/core-concepts#user)): `metadata.summary_id`
This can include time spent in bed while awake, if recorded by the wearable.
See [GET sleep](https://docs.tryterra.co/reference/health-and-fitness-api/readme#sleep) for the full Schema, example, & descriptions of each field
Menstruation: menstrual metrics for the user for a given day
Unique identifier (per [User](https://docs.tryterra.co/reference/health-and-fitness-api/core-concepts#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](https://docs.tryterra.co/reference/health-and-fitness-api/readme#menstruation) for the full Schema, example, & descriptions of each field
Planned workout: a step by step workout plan for the end user
Unique identifier (per [User](https://docs.tryterra.co/reference/health-and-fitness-api/core-concepts#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](/unified-api/write-data.md#writing-planned-workouts) for more info
You can find more details about these **Data Events** in the [Event Type](https://docs.tryterra.co/reference/health-and-fitness-api/event-types) reference.
You can find all your received events (payloads) in your [Terra Dashboard > Events](https://dashboard.tryterra.co/dashboard/debug).
{% hint style="warning" %}
**Overwriting/Updating data**
* Whenever you receive an event for a [User](https://docs.tryterra.co/reference/health-and-fitness-api/core-concepts#user) which constitutes a duplicate, based on the data type's unique identifier (listed above), 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 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 %}
## 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="" %}
{% prompt description="Resend an event to test your webhook handler" icon="terminal" openInAIProviders="true" defaultExpanded="full" %}
```markdown
Resend the most recent sleep event for user 8f2a1c to my webhook so I can test my handler.
Use the Terra CLI: brew install tryterra/tap/terra, or npm install -g @tryterra/cli, then terra login. Run terra docs ask --question "" for anything you need from the Terra docs, and terra --help for usage.
```
{% endprompt %}
## Check your setup
1. **Set up**: Have you tested that your destination can receive data payloads from Terra?
2. **Connect a user**: Have you connected a user via Terra? Have you received an Authentication Event?
3. **Receive 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, see [Troubleshooting](/unified-api/debugging-faq.md) to check the user's data is synced properly.
## Next steps
* [Historical data requests](/unified-api/requesting-historical-data.md): backfill data from before the user connected.
* [Writing data to providers](/unified-api/write-data.md): send planned workouts back to a user's provider.
* [Troubleshooting](/unified-api/debugging-faq.md): find out why an expected event did not arrive.