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:

  1. Health Data Events: sent to your destination when new data is available on the user's account.

  2. How to test your Destination: Terra sends events to your destination, learn how to test this.

  3. Common errors and troubleshooting: when not receiving expected data.

Prerequisites


1. Types of Health Data Events

Data Events fall under one of the following categories:

(1) Activity: A tracked workout, with a defined start and end time.

For example, an End User pressing "start run" on their watch, going for a 5k run, and pressing "end run"

(2) Daily: the total daily summary of the user's activity up to the point in time of the event

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.

(3) Body: the recorded body metrics for the user for a given day

body payloads are always relevant to a given 24 hour period, defined by the start_time and end_time of the metadata key.

(4) Sleep: a tracked sleep session, with a defined start and end time.

This can include time spent in bed while awake, if recorded by the wearable.

(5) Menstruation: menstrual metrics for the user for a given day

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.

You can find all your received events (payloads) in:

Overwriting/Updating data

Example of a Health & Fitness Payload

Data Events will take the following form:

ActivityPayload.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"
}

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

Last updated

Was this helpful?