Notification API

back to API Documentation (up a level)

API Overview

The 'Notification API' specifies the types of messages and the message contents of the HTTP Notification callbacks.

The subscription lifecycle

We can think of a 'subscription' and it's notification messages as having a 'lifecycle'.

  1. Initialisation - When a subscription is created, an initial notification message is sent. This initial notification can be used by the target application to perform any initialisation procedures (for example insert a new record into a database).
  2. Change Notifications - After this initial notification, the target appliation should expect to recieve (zero or more) 'data change' notifications. These are the 'normal' notifications used to indicate that a particular profile data item has an updated value.
  3. Termination Notifications - Finally, there are a number of 'termination' notifications that can be sent. Termination notifications inform the target application that, for a variety of reasons, there will be no further notifications from the given subscription.

Notification Messages

When LiveDirectory 'fires' a notification, it calls the exact URL specified for the corresponding subscription (importantly as an HTTP POST request). However, additional post parameters are added automatically to enable a target application to manage the notifications and more importantly to do cool, mind-bending stuff with updated profile content.

(Question: What if the target application wants to 'unsubscribe' itself? Do we need a unique 'id' for each notification? Do we need to send a 'subscription' id?)

Notification data common to all notification message types

Parameter Name Parameter Contents
ld_notification_type Any one of: [ subscribed | data_value_changed | data_added | data_deleted | data_path_deleted | unsubscribed ]
ld_profile Name of the data profile
ld_profile_data_path Complete data profile path, eg: "[profile name]/foo/bar".

Initialisation Notification

message type: subscribed

Change Notifications

message type: data_value_changed

Parameter Name Parameter Contents
ld_data_value The new/updated value of the given 'profile data path'. Currently this parameter will contain json formatted data.
ld_data_format Currently only 'json' is supported so the value will always be "json".

message type: data_added

message type: data_deleted

Termination Notifications

message type: data_path_deleted

message type: unsubscribed