> 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 [Data generator](https://dashboard.tryterra.co/dashboard/generate) to send test data to your destination.

## Data event types

When a connected [user](https://docs.tryterra.co/introduction/core-concepts#users) 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.

The event's `type` is its data type:

| Type           | Holds                                                                                                              |
| -------------- | ------------------------------------------------------------------------------------------------------------------ |
| `activity`     | One tracked workout with a start and end time, such as a 5k run between pressing start and stop.                   |
| `sleep`        | One sleep session. It can include time in bed while awake, if the wearable records it.                             |
| `daily`        | The running total for one day so far, such as steps and calories. Use only the date part of `metadata.start_time`. |
| `body`         | Body metrics for one day, such as weight or blood glucose.                                                         |
| `nutrition`    | The food logged in one day.                                                                                        |
| `menstruation` | One day of the menstrual cycle: phase, flow and anything logged.                                                   |
| `athlete`      | The end user's profile on the provider.                                                                            |
| `hormone`      | One hormone test result.                                                                                           |

The [event types reference](https://docs.tryterra.co/reference/health-and-fitness-api/event-types#data-events) lists every type with its format, and the [data models](https://docs.tryterra.co/reference/health-and-fitness-api/data-models) give every field.

You can find all your received events (payloads) in your [Terra Dashboard > Events](https://dashboard.tryterra.co/dashboard/debug).

{% hint style="warning" %}
The same payload can arrive again with more data. Each new copy is a superset of the last, so overwrite your stored record instead of adding a new one. Match the two by the payload's unique key, listed in [uniquely identifying payloads](https://docs.tryterra.co/reference/health-and-fitness-api/data-models#uniquely-identifying-payloads).
{% 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="<https://app.arcade.software/share/U79B7Z7lfR85jSKUIIVF>" %}

{% 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 "<question>" for anything you need from the Terra docs, and terra <command> --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.
