Event Types

Summary

View all event types that you may receive from your webhook. Below the tables is a detailed look at what is included in each event type.

Below, we have documented how we recommend responding to event types and what format to expect.

Misc

healthcheck [BETA]

This will periodically be sent to your webhook to inform you of the recent trends in payload volume.

Note that this format is subject to change, and is still undergoing testing and validation

{
  "type": "healthcheck",
  "status": String,
  "creation_timestamp": String,
  "trend_percentage": Number,
  "sent_webhooks_last_hour": Number
}

Authentication

{
	"type": "rate_limit_hit",
  "user": TerraUser,  
  "start_date": Date,  
  "end_date": Date,
  "retrying_at": String,
  "message": "Rate limit reached whilst processing async query"
}

auth

If successful, you should add the user to your database. You can use widget_session_id to link back to the user who you submitted the widget link to.

{
  "type": "auth",
  "user": TerraUser,
  "status": "success",
  "reference_id": String,
  "widget_session_id": String
}

{
  "type": "auth",
  "user": TerraUser,
  "status": "error",
  "message": "User failed to authenticate and has been deleted",
  "reason": String,
  "reference_id": String,
  "widget_session_id": String
}

deauth

Remove the user from your database.

{
  "type": "deauth",
  "user": TerraUser,
  "status": "success",
  "message": "User has deauthenticated"
}

user_reauth

Remove old_user from your database and replace old_user with new_user for all records tied to them.

{
  "type": "user_reauth",
  "new_user": TerraUser,
  "old_user": TerraUser,
  "status": "warning",
  "message": "User has reauthenticated and old ID has been deleted"
}

access_revoked

Remove the user from your database and remove all their records.

{
  "type": "access_revoked",
  "user": TerraUser,
  "status": "warning",
  "message": "User revoked access"
}

connection_error

We submit this event type when a provider no longer allows access to a user's data. Deauthenticate the user and request that the user reauthenticates.

{
  "type": "connection_error",
  "user": TerraUser,
  "status": "warning",
  "message": "User connection degraded"
}

google_no_datasource

Add the user to your database but inform them that they do not have any health datasources.

{
  "type": "google_no_datasource",
  "user": TerraUser,
  "status": "warning",
  "message": "User has no datasources available"
}

{
  "data": Sleep,
  "user": TerraUser,
  "type": "sleep",
  "version": String
}

Data requests

processing

Occurs when data needs to be fetched asynchronously from the data provider. Terra will make the necessary requests to fetch this data, and it will be sent through automatically via webhook. You can also safely request for it after the time in the retry_after_seconds field. Note that the data may be available sooner than the time noted as well. The retry_after_seconds gives an upper bound to it to make sure that you can receive this data after this time.

{
	"type": "processing",
  "status": "success",
  "message": "Request is processing, try again later",
  "user": TerraUser,
  "retry_after_seconds": Number,
}

large_request_processing

Occurs when a large request (>1 month of data) has been submitted to the rest API, and chunks of data will be sent following this webhook, capped at the least of 10MB each or 10 objects each within the list of data
The reference field will be included as a terra-reference header in every data payload following this hook

{
	"type": "large_request_processing",
  "status": "processing",
  "message": "Large request is processing",
  "user": TerraUser,
  "reference": String
}

large_request_sending

Occurs when a large request (>1 month of data) has been submitted to the rest API, and chunks of data are sent following this webhook
The reference field will be included as a terra-reference header in every data payload following this hook

{
  "user": TerraUser,
  "reference": String,
  "message": "Large request is being sent",
  "expected_payloads": Number,
  "type": "large_request_sending",
},

rate limit during async

If rate limits are reached during an asynchronous request, we reschedule the request.

{
  "user": TerraUser,  
  "start_date": Date,  
  "end_date": Date,
  "retrying_at": String,
  "message": "Rate limit reached whilst processing async query",
  "type": "rate_limit_hit",
}

activity

Parse the data using the Data Models page and update your user with the new data.

{
  "data": [Activity],
  "user": TerraUser,
  "type": "activity",
  "version": String
}

athlete

Parse the data using the Data Models page and update your user with the new data.

{
  "athlete": Athlete,
  "user": TerraUser,
  "type": "athlete",
  "version": String
}

body

Parse the data using the Data Models page and update your user with the new data.

{
  "data": [Body],
  "user": TerraUser,
  "type": "body",
  "version": String
}

daily

Parse the data using the Data Models page and update your user with the new data.

{
  "data": [Daily],
  "user": TerraUser,
  "type": "daily",
  "version": String
}

menstruation

Parse the data using the Data Models page and update your user with the new data.

{
  "data": [Menstruation],
  "user": TerraUser,
  "type": "activity",
  "version": String
}

nutrition

Parse the data using the Data Models page and update your user with the new data.

{
  "data": [Nutrition],
  "user": TerraUser,
  "type": "nutrition",
  "version": String
}

sleep

Parse the data using the Data Models page and update your user with the new data.

{
  "data": [Sleep],
  "user": TerraUser,
  "type": "sleep",
  "version": String
}