📘

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==

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"
  }
]

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.