Webhook and Integration

How do I connect my app to Terra?

Terra works with Webhooks - our service will push data to you. A simplified integration involves three steps: setting up webhook, connecting users, requesting data.

  1. Setting up a webhook and getting cred entials You will be given an API key and a Dev ID. You will also need to setup a webhook to which health data is pushed.
  2. Connecting with users via the widget Put simple, you can present your user with a dedicated URL that we provide you. The URL is unique for every user session. Through this session, the user registers their wearble with Terra, and you receive the user ID for that user
  3. Requesting data Now that you have a user ID, you can request health data from Terra for that particular user! The data is either pushed to your webhook or sent directly in your request reponse based on your preferences

What is the type of the callback provided?

Terra sends data to your webhook URL using POST requests


When a user registers using the widget, how can we get their user_id?

The user_id will be sent to your webhook. It will also be available in the final redirect URL specified for the widget session

How can we deauthenticate users who wish to do so?

You can do so using our /deauthenticateUser endpoint

Do we get a success message to our webhook when a user authorisation is successful?

There is still a possibility for auth to fail after redirection. For example, the user might close the application. They might also not grant access to all the necessary data scopes. In these cases, you will get a an auth failure hook event

How do we use the reference_id in a widget session?

You can provide the reference_id when generating the session, and it'll be returned to you in your webhook upon user authentication completion so that you can link the user_id to whichever reference_id you completed authentication for

If the same user account is authenticated for 2 different dev IDs, will both dev IDs maintain the user?

Yes! Terra allows a user’s single account to be associated with multiple applications that use Terra

How can we ensure that we don't create a duplicate account if someone happens to authenticate twice with the same provider?

If a user authenticates a second time, their old Terra entry gets deleted

Data Requests

How can I specify a date range if I want to pull historic data?

You can use the start_date and end_date parameters (by default end_data , if not set, is one day after start_date)

How do we handle timezones for date specifications?

The API accepts UNIX timestamps to avoid confusions. Otherwise, we fetch all the data based on UTC time

How often do I receive data on my webhook?

The frequency at which Terra sends you data is fully customisable: it can be as high as every 5 minutes or as little as once a day. Our recommendation would be at least 3 times a day

Can I distinguish sensor data from manually added data?

Where applicable, yes! There would be an upload_type field specifying how the data was uploaded


Is there a limit to how far back the start date can be for each provider?

Terra does not set a limit. The limit will be determined by the provider’s data availability. For example, if a user started using a wearable in Jan 2015, no data will be returned for request beyond that date

Can I remove a specific provider from a user (if they are signed in with multiple providers)?

Each user ID that we provide is linked to a single provider, you pass the user ID to the deauthorize endpoint to deauthorize that provider

How do we enable Google Fit for syncing?

Users would need to select in the following order:

  • Settings
  • Accounts
  • Select your Google account being used for Google Fit
  • Ensure that Google Fit is enabled for syncing