Getting data into your project

Learn how to set up a webhook endpoint and how to ingest data coming from Terra

Terra uses webhooks to notify your application when new data is available for a given user_id. Webhooks are particularly useful for events such as when a user completes a workout, their wearable syncs to the cloud, or they log a new measurement in their fitness app.

How Terra uses webhooks

A webhook enables Terra to push real-time notifications to your app. Terra uses HTTPS to send these notifications to your app as a JSON payload. You can then use these notifications to execute actions in your backend systems. To learn more, see Terra webhook events.

Steps to receive webhooks

  1. Create a webhook endpoint as an HTTP endpoint (URL) locally, and use a service such as Ngrok to reverse proxy requests from a URL to your localhost. (see Customize API settings for how to edit your Webhook URL
  2. Handle requests from Terra by parsing each event object and returning 2xx response status codes.


Webhook retries

If your server fails to respond with a 2xx response code or the request times out, the webhook will be retried a number of times in the future. For more information, see Webhook Retries