Compendium Documentation

Introduction

The Callback Resource provides event-driven interoperability between Compendium Blogware and other applications. In software development, the term callback refers to a pre-specified operation that should take place as the side effect of the occurrence of an event. Within the context of Compendium Blogware, a callback is implemented as an HTTP POST operation to a pre-specified URL hosted by a third party, usually the owner of the network or an OEM partner. The request contains data about the event itself as well as data to verify the authenticity of the message.

To employ the Callback resource, an organization with a blog network must do the following:

• Determine which events within the application may be of interest.
• Create one or more web service endpoints to accept the HTTP POST request.
• Register the newly created endpoint(s) with Compendium Blogware using the Callback resource.

The rest of this document is devoted to a discussion of the implementation details. In the discussion that follows, the term event request refers to the HTTP request submitted by Compendium Blogware to a third party web server, containing data about the occurrence of an event.

Event Types

Resource operations which fire events will have information about those events and their payloads in their reference documentation.

Callback Management

Compendium Blogware provides a Callback resource for adding and removing callbacks as well as retrieving information about existing callbacks on an individual or group basis.

Only JSON is supported as an output type for callback management operations. This SHOULD be specified via the HTTP Accept header, but it can also be made via the URI, e.g. /app/callback/json.

Registration requests require that an access key be available for the user making the request. Keys are available only to networks where API access is enabled. Contact your account manager to learn more about getting access to this feature.

Callback Descriptors

Information about a callback's parameters is expressed as a callback descriptor. This structure is used both in registration of new callbacks and retrieval of information about existing callbacks. The callback descriptor specifies any number of required attributes for successfully executing the callback. The validity of the descriptor is dependent upon the callback version number.

Variable substitution is supported in the descriptor, use the format $VariableName where VariableName is the name of the variable to substitute. Variable names and their potential values are documented at each service endpoint. If a field in the callback descriptor can use variable replacement it is noted in the version format specifier below.

Version 1 Callback Descriptor Format

Version 2 Callback Descriptor Format

This version is not currently supported, but will be in subsequent releases.

If the CallbackType is "synchronous", the request will wait on the response and use it before continuing execution.

Deliverability

While we will make a best effort to promptly deliver all callback notifications, messages are not guaranteed to be delivered. They may arrive multiple times, and there is no guarantee for order. All event requests have a 15 second timeout. If the request fails, retry attempts will be made over a 24 hour period. This allows your service endpoint to receive messages even if it is down for short maintenance windows.

HTTP Response Codes

Web services should respond to the HTTP POST request with a 2XX response code to indicate successful delivery. Redirects (3XX response codes) are not followed, and no further delivery attempts will be made. All other response codes, as well as request timeouts, are treated as failures and will be retried.

Callback Data Security

The Compendium callback system can be used in a way that protects data secrecy, ensures data integrity, and verifies sender authenticity.

When a callback is registered with the application, the endpoint may be specified as using HTTP either with (http) or without SSL (https. Using SSL ensures that the callback data is transmitted over an encrypted channel. The application does not currently validate your server's certificate, so your endpoint's host may use a self-signed certificate.

To guard against submission of random data to your event request endpoint, all messages submitted by Compendium include a keyed-Hash Message Authentication Code (HMAC) that can be used to verify the integrity of the message and the authenticity of the sender. Implementation details of the HMAC are given below.

Request Data Authentication

The Compendium callback service uses the HMAC-SHA256 algorithm for event request data authentication. The HMAC is seeded using the unique access key associated with the user who registered the callback with the application. For networks which have API access, this key is visible on a user's account settings page and it may be retrieved using an API endpoint.

The HMAC value is supplied with the event request using the HTTP header Compendium-Callback-Hmac. The header value is a 64-character hexadecimal string. By combining the registering user's access key and the event request's HMAC value, you can authenticate the request.

Additionally, the payload format includes a nonce, a randomly generated string which is used as part of the HMAC creation process. The inclusion of this value is used to guard against replay attacks.

Notification Format

The notification data will be supplied in the body of the HTTP POST request. The recognized forms of serialization are JSON (application/json) and web form (application/x-www-form-urlencoded). If no ContentType parameter was specified during the callback registration, the data will be serialized as JSON by default.

JSON

The notification format is a JSON encoded object of the following format.

 {
   "EventName": string, // name that identifies the type of event fired,
   "FiredAt": string, //  timestamp recording event occurrence, expressed in ISO 8601 format
   "Nonce": string, // Pseudo random string used for preventing replay attacks
   "Payload":  object // data associated with the event
 }

The object is supplied in the body of the HTTP request, and the accompanying Content-Type header is application/json.

Web Form

The notification format is a URL-encoded list of parameter name/value pairs, as described in the HTML 4.01 specification and RFC 1738.

The members of the payload object are expressed using the form array notation supported by PHP. For example, if the Payload object has a member named "foo", then the parameter name would be Payload[foo].

The object is supplied in the body of the HTTP request, and the accompanying Content-Type header is application/x-www-form-urlencoded.