Receive data updates

Learn how to receive data update events to your app as soon as the user's data syncs to the cloud

Prerequisites

In order to receive events, you'll need to

• have an active Destination (guide here)

• have enabled the Data Sources you want (guide here)

If you missed any of the steps above, please refer to the respective guides.

Once you have the above set up, you'll be ready to receive events.

Terra sends updates via events to your destination. Familiarize yourself with the types of events and their payloads:

• Authentication events occur when a user connects/disconnects their health & fitness data account

• Data events occur when new data is available on the user's account

• See Common errors and troubleshooting

Data events

Whenever a User has new data available on the respective platform they use, you will receive a data update under one of the following categories

Overwriting/updating data

Whenever receiving 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.

Use the unique identifier for each payload (detailed below) to overwrite data appropriately upon receiving an update

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

Unique identifier (per User): metadata.summary_id

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

See GET 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): 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 for the full Schema & descriptions of each field

Body: the recorded body metrics for the user for a given day

Unique identifier (per 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 for the full Schema & descriptions of each field

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

Unique identifier (per User): metadata.summary_id

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

See GET sleep for the full Schema, example, & descriptions of each field

Menstruation: menstrual metrics for the user for a given day

Unique identifier (per 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 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): 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 for more info

Data updates 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"
}

Any other event types & their explanations will be found in the Event Type reference

Testing

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.

Common errors & troubleshooting

Help! My destination is erroring (retries)

If your destination returns an error code (e.g. your server responds to a webhook event with a 5XX http status code), not to worry! Terra retries to send that event, with exponential backoff, over a period of a little over 24 hours. This ensures that if your server experiences downtime of up to a day, you will still receive any missed data, hence maintaining data integrity.

Data is shown on my Fitbit/Garmin/etc... app, but hasn't been sent yet

Terra sends data automatically as soon as it is available on a data source's cloud. That means that if the wearable hasn't synced to the respective app on the end user's phone, or if the app has not synced to the cloud, Terra will be unable to retrieve that data. Wait a bit longer, or try to force a sync (using a "pull down to sync" feature or equivalent available in most apps)

In order to verify if the data has synced to the respective cloud, you may instruct the user to go on their web dashboard for their device using a browser to verify the data is present.