The HealthVault platform now provides the ability to notify applications when specific conditions are met.

A scenario

A blood-pressure-tracking application wants to be notified whenever a new blood pressure measurement is added to any of the user records that the application has access to, so it can perform some operation with the data.

With previous releases, the only way to do this was for the application to periodically call GetUpdatedRecordsForApplication(), and then look at each record that was updated to see if the update was a new blood pressure instance.

The solution

Each application can now create a series of subscriptions, where each subscription specifies the event to detect and how to notify the application when the event occurs.

The BloodPressureTracker application creates a new subscription, specifies that it wants to be notified when a blood pressure measurement is added, updated or removed, and that the notification should be sent to www.example.com/notificationBloodPressurePage.ashx. The subscription is persistent until the application deletes it.

The notification page must be in a location that is accessible to HealthVault, which means it is accessible to other internet programs. To allow the application to verify that a notification came from the HealthVault platform, the application registers a key with the subscription, and when the notification arrives the application can verify that the HMAC in the message is identical to one computed by the application.

The life and times of a notification

Notification Dispatch

The dispatching of a notification happens on the HealthVault Platform.

  • An operation such as PutThings is performed on the HealthVault Platform.
  • The HealthVault platform finds subscriptions that match the event.
  • The HealthVault platform notifies the application using the following steps:
  • The key registered with the matching subscription is used to create an HMAC of the notification payload.
  • That hash, a version id that was specified with the key, and the subscription id are included in the Authentication header of a request.
  • The request is sent to the URL defined in the subscription as a POST with the XML notification text as the POST payload.
  • The server waits for a response.
  • If it gets a “200 OK” response, it considers the notification to be delivered.
  • If it gets any other response or does not receive a response, it will hold onto the notification and try again later.
  • If the notification cannot be delivered after a period of days (currently set to 10 days but subject to change), the notification is abandoned.

    Notification Processing

    The notification processing happens in the HealthVault application.

  • The notification handler reads the XML notification text into a string.
  • The key version id, subscription id, and HMAC of the notification payload are extracted from the authentication header.
  • The notification handler determines which subscription was notified based on the key version id that was passed.
  • The expected key is determined based on the key version id that was passed. This allows keys to be updated to new versions while not breaking the handling using the old keys.
  • An HMAC of the xml notification text is calculated, and compared to the one passed in the header. If the hmac does not match the notification should be ignored and discarded as it did not originate from the HealthVault service.
  • The notification handler returns a status of “200 OK” so that the HealthVault platform knows that the delivery was successful.
  • The XML notification text is processed.

    The processing of the notification should be performed on a separate thread to prevent the possibility of taking so much time that the timeout is reached.

    Event types and notification methods

    For this release, the platform supports one event type – a change (add/update/delete) of an instance of a specific set of data types in a user’s record – and one delivery method – over an https: connection. We are planning to extend support in future releases – if you would like to influence which events and delivery methods we consider, please send us feedback.

    Health Record Item Changed Event details

    The health record item changed event passes the following information in the notification:

    • The person id and record id that specify the record in which the change was made.
    • A list of the health record item ids (aka “thing ids”) that were changed.

    After the notification is received the application will need to fetch the item to determine what change was made. If the object was deleted, it will not be returned from the fetch operation.

    Limitations

    Notification URL

    The notification URL must be on the same domain as the action url that is registered with the application.

    Authorization

    The user must have granted the application offline read access to the data type that the subscription refers to.

    Number of subscriptions

    An application can only register 25 subscriptions at a time. This number is subject to change.

    Delivery timeliness and guarantee

    The HealthVault platform makes a “best effort” to deliver each notification in a timely manner, but does not guarantee delivery. It is not designed for real-time monitoring scenarios.

    Notification of changes only

    Notifications are delivered only for changes that are detected in records – the platform does not notify for items that are already existing in a record when the user first authorizes the application, nor does it notify for deletion if a user de-authorizes the application.

    Eventing sample and test application

    We have created a sample application which serves three purposes:

    1. It demonstrates how to use the subscription manager api calls to create, modify, and delete subscriptions.
    2. It provides a sample implementation of a subscription notification handler that processes incoming notifications.

    Getting started

    The first time that you run the application, it will generate an application id and a key for you to use. The sample will tell you how to properly define these in the web.config file.

    Managing subscriptions

    The management part of the application is pretty simple – you merely add a new subscription and then list the data type ids that you want to be monitored.

    Testing notification handlers

    In many cases, developer machines are not directly reachable from the internet and therefore there is no address that can be used in a subscription. To make it easier to develop notification handlers, the sample application can send simulated notifications to a notification handler for debugging purposes. It provides the following options:

    Notification Destination

    Choose between the URL defined in the subscription, the test notification handler defined in the project, or a URL that you enter.

    Authentication

    Choose Normal to have correct authentication headers, send bad HMAC to send an HMAC that is incorrect, or send bad key version to send a key version that is different than the one in the subscription.

    Instances

    The sample application can generate fake instance ids (if you just want to check that the notification handler is set up correctly), send an empty instance list, or select actual instance IDs from the current record.