Human API Developer Hub

Welcome to the Human API Developer Hub. You'll find comprehensive guides and documentation to help you start working with Human API as quickly as possible. Let's jump right in!

Get Started

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

Set Up a POST Endpoint to Receive Notifications

Create Endpoint

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

Failed notifications may be discarded and continuous failures may result in notifications being disabled for your app. You can later reactivate notifications in the Developer Portal.

HTTP/HTTPS

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

Update Developer Portal

After creating an endpoint to receive notifications, you must then add it to your Human API account.

To do so, log into the Developer Portal, click the appropriate app and navigate to the Notifications page. On the Notifications page, check "Enable notifications", add the URL of the endpoint that you created in the "Notify URL" field and Save Changes.

Testing Your Notifications Endpoint

To test your newly created endpoint, simply add a user to your application and connect a device. This should trigger a Notification from Human API that will display on the righthand side of the notifications page in blue as shown above.

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==
property
type
description

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

[{
	"humanId": "1cb3eb4ddef09ff8f59f990c104c31ac",
	"updatedAt": "2016-02-02T02:10:40+00:00",
	"type": "activitysegment",
	"model": "activitysegment",
	"action": "created",
	"objectId": "56b01020131e6208005bc346",
	"endpoint": "https://api.humanapi.co/v1/human/activities"
}, {
	"humanId": "1cb3eb4ddef09ff8f59f990c104c31ac",
	"updatedAt": "2016-02-02T02:10:40+00:00",
	"type": "activitysummary",
	"model": "activitysummary",
	"action": "updated",
	"objectId": "56b01020131e6208005bc351",
	"endpoint": "https://api.humanapi.co/v1/human/activities/summaries"
}]
property
type
description

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

Indicates the type of a measurement object.

model

String

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:

{
	"humanId": "1cb3eb4ddef09ff8f59f990c104c31ac",
	"updatedAt": "2016-02-02T02:10:40+00:00",
	"type": "activitysegment",
	"model": "activitysegment",
	"action": "created",
	"objectId": "56b01020131e6208005bc346",
	"endpoint": "https://api.humanapi.co/v1/human/activities"
}

The appropriate query to generate would be:

//endpoint+objectId+"?access_token="+(accessToken from humanId)
https://api.humanapi.co/v1/human/activities/56b01020131e6208005bc346?access_token=<accessToken-for-humanId-1cb3eb4ddef09ff8f59f990c104c31ac>

Notifications

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