Notifications

Using notifications, you can be notified when a user has connected a device or when new data is available.

πŸ“˜

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:

var crypto = require('crypto'); //npm install crypto-js --save
// ...

var payload = '{"contents":"supersecretstuff"}';
var timestamp = 1403591492088;
var nonce = 105850310064852240;

var clientSecret = 'itsfullofsecrets';

// crypto.createHmac(algorithm, key)
var signature = crypto.createHmac('sha1', clientSecret).update(payload + timestamp + nonce).digest('base64');

//Correct Result:
//signature == "fQkvPoMVwsZWM4/r4VrKlMaCOAw="

//
using System;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Security.Cryptography;
using System.IO;

namespace test
{
	class MainClass
	{
		public static void Main (string[] args)
		{
			string payload   = "{\"contents\":\"supersecretstuff\"}";
			string timestamp = "1403591492088";
			string nonce	 = "105850310064852240";

			byte[] signature = GenerateSignature("itsfullofsecrets", payload + timestamp + nonce);

			Console.WriteLine(Convert.ToBase64String(signature));
		}

		public static byte[] GenerateSignature(string secret, string content)
		{
			HMACSHA1 myhmacsha1 = new HMACSHA1(Encoding.UTF8.GetBytes(secret));
			MemoryStream stream = new MemoryStream(Encoding.UTF8.GetBytes(content));
			return myhmacsha1.ComputeHash(stream);
		}
	}
}

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

Content-Type: application/json; charset=utf-8
User-Agent: HumanAPI/1.0

X-HumanAPI-Nonce: 105850310064852240
X-HumanAPI-Timestamp: 1403591492088
X-HumanAPI-Signature: ZTQ0MDg3MmExYjg5ZmYOTA3Y2M4Zjc4NQ==
propertytypedescription
Content-TypeStringPayload type, always set to application/json
User-AgentStringHumanAPI plus the notifications version (currently only 1.0)
X-HumanAPI-NonceStringUnique string used in calculating X-HumanAPI-Signature.
X-HumanAPI-TimestampIntegerUnix timestamp in seconds.
X-HumanAPI-SignatureStringHMAC-SHA1 signature calculated from String(payload + timestamp + nonce) using your app's clientSecret as the key.

POST Payload Structure

[
  {
   "updatedAt":"2018-07-30T23:30:17.865Z",
   "humanId":"4c7424188d8a750d0e15e17318775dc0",
   "endpoint":"https://api.humanapi.co/v1/human/medical/test_results",
   "type":"testresult",
   "model":"testresult",
   "action":"created",
   "objectId":"5b5f9f89f1560cf08ed64e56"
  },
  {
   "updatedAt":"2018-07-30T23:30:17.809Z",
   "humanId":"4c7424188d8a750d0e15e17318775dc0",
   "endpoint":"https://api.humanapi.co/v1/human/medical/medications",
   "type":"medication",
   "model":"medication",
   "action":"created",
   "objectId":"5b5f9f89f1560ca43cd64e53"
  }
]
propertytypedescription
humanIdStringThe unique Human API ID of your app user.
updatedAtDateThe time at which the record was last updated on our servers (in UTC).
typeString[deprecated] Indicates the type of a measurement object.
modelString[deprecated] The updated record's model.
actionStringEither created or updated
objectIdStringThe record's unique ID, which can be added to the request route to grab only the updated record.
endpointStringThe 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:

{
 "updatedAt":"2018-07-30T23:30:17.809Z",
 "humanId":"4c7424188d8a750d0e15e17318775dc0",
 "endpoint":"https://api.humanapi.co/v1/human/medical/encounters",
 "type":"encounter",
 "model":"encounter",
 "action":"created",
 "objectId":"5b5f9f89f1560c1c55d64e4f"
}

The appropriate query to generate would be:

-H "Authorization: Bearer accessToken-for-humanId-1cb3eb4ddef09ff8f59f990c104c31ac"
https://api.humanapi.co/v1/human/medical/encounters/5b5f9f89f1560c1c55d64e4f

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.