GuidesAPI ReferencePortalSupport and Knowledge baseIntegration Status

Syncing User Data

Notifications are one way to keep you user's information up-to-date. For best practices, see [Keeping User Data Up-to-date](🔗).

Human API Notifications will alert your application when a user has connected a device or has new data that is available to pull. Specifically, notifications are **sent whenever Human API servers receive new or updated user data, or sync status update, ** and are thus a great way to keep local user data within your app in sync.

In order to take advantage of notification functionality, there are a few steps that you will need to take described below.

## How to enable notifications

Notifications are enabled by Human API Support. If you would like to turn this feature on, please send us an email to [[email protected]](🔗) (or contact your Account Manager) complete with URL to deliver POST notifications to.

## Set Up a POST Endpoint to Receive Notifications

Notifications are sent via a POST request to a specified endpoint on your server. Please create a dedicated endpoint and ensure that this endpoint:

  • Is publicly accessible

  • Accepts POST requests

  • Replies with a `200` status code within 3 seconds

HTTP/HTTPS

Both HTTP and HTTPS endpoints are supported, though the latter is preferred for production environments.

Testing Your Notifications Endpoint

To test your newly created endpoint, simply add a user to your application and connect to one of the [Starfleet demo sources](🔗). This should trigger a series of Notifications from Human API through your endpoint.

## Authenticate Notification with HMAC-SHA1 Signature (optional)

Along with HTTPS, using the notification signature (`X-HumanAPI-Signature`) is a good way to ensure that notifications are entering your system securely.

The HMAC-SHA1 signature is calculated using `String(payload + timestamp + nonce)` as the message and your app's `Client Secret` (found under the Settings tab) as the key. For Node.js, we recommend that you use [`crypto-js`](🔗) for this calculation like so:


There are also standard HMAC-SHA1 libraries for most languages.
Testing Your Signature
Use the demo data in the example above to test your implementation.
Correct Result : `fQkvPoMVwsZWM4/r4VrKlMaCOAw=`
From now on, so long as the `X-HumanAPI-Signature` == your calculated signature you can ensure that each notification is from us. If these values are not equal, you should ignore and not respond to that request.
## Parse the Notification Payload
Notifications will be batched for performance, meaning that each notification may contain entries for multiple users.

Please note that only the app's owner can modify the notification settings.
# POST Header Structure

propertytypedescription
`Content-Type``String`Payload type, always set to `application/json`
`User-Agent``String``HumanAPI` plus the notifications version (currently only 1.0)
`X-HumanAPI-Nonce``String`Unique string used in calculating `X-HumanAPI-Signature`.
`X-HumanAPI-Timestamp``Integer`Unix timestamp in seconds.
`X-HumanAPI-Signature``String`HMAC-SHA1 signature calculated from `String(payload + timestamp + nonce)` using your app's clientSecret as the key.
# POST Payload Structure

propertytypedescription
`humanId``String`The unique Human API ID of your app user.
`updatedAt``Date`The time at which the record was last updated on our servers (in UTC).
`type``String`_[deprecated]_ Indicates the type of a `measurement` object.
`model``String`_[deprecated]_ The updated record's model.
`action``String`Either `created` or `updated`
`objectId``String`The record's unique ID, which can be added to the request route to grab only the updated record.
`endpoint``String`The endpoint to which you can append the user's `accessToken` to query for data.
# Models & Type
Deprecated
Model/type information has been deprecated. Instead, design your processing system to use the `endpoint` URL (see below for details).
## Responding To Notifications
To respond to the notification and query for the updated data, simply use the provided `endpoint` and `objectId` attributes along with the `accessToken` on your server that corresponds with the provided `humanId`.
So, for the following notification:

The appropriate query to generate would be:

## Notification behaviors
## Wellness
When a user connects a Wellness account, notifications are sent for historical data and new data—even if the user has connected the account using Human API previously.
## Medical
When a user connects their live Medical account, historical data will be collected and notifications will be sent. However, if the user connects the same account somewhere else using Human API (such as an internal test account that has already been connected before), notifications will not be sent. Please use a live and unique set of patient portal credentials in order to receive notifications. 
Alternatively, you may also [use our Starfleet credentials](🔗) in order to simulate notifications.
Where are notifications for social histories, organizations and demographics?
We are in the process of building notifications for social history endpoint. Data related to organizations are folded into /sources, so extraneous notifications are not expected. Demographics endpoint will be deprecated, so notifications should not be expected for that data.