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'.
- 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).
- 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.
- 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". |