Register a Callback with the Application

Operation Summary:

Registers a URL for receiving event callback HTTP requests.

Resource URL:

https://api.compendiumblog.com/app/callback

HTTP method:

POST

HTTP Status Codes:

201 Created

403 Forbidden

HTTP Status Code Details:

201 Created: The callback was registered successfully.
403 Forbidden: The user invoking the endpoint is not authenticated or does not have appropriate authorization to perform the operation

Response Representations:

JSON

Permitted Roles:

Super Administrator

Super Delegate

Network Administrator

Required Parameters:

EventName: The name of the event to register a callback handler for. Available callbacks are listed at the documentation for each service endpoint.
CallbackVersion: An integer specifying the version of the callback descriptor format being used.
CallbackDescriptor: The descriptor to use for the callback. Depends on the CallbackVersion. See the Callback Implementation Guide for further information.

Optional Parameters:

NetworkId: The network for which the callback will be associated. May be a valid network ID or '-00000-00000-00000-00000-00000-00000' to indicate that the callback should be registered in a global context. See "Additional Notes" subsection for details on which roles may supply this parameter.

Response Values:

Success: The callback was registered successfully.
Error: The callback was not registered successfully.

Response Structure:

Responses are single-member objects which have a property name based on the type of result.

The Success result will look like:

{ 'Success' : string}

Where the string is the system assigned unique identifier for the newly registered callback.

The Error result will be a flat array of objects, which have keys for the message name and explanatory text.

{
     'Error' : [
       { 'Name' : string, 'Message' : string },
       { 'Name' : string, 'Message' : string },
       ...   
    ]
 }

Error Types:

Write: Failed to register callback
EventName: Invalid or no event name specified
CallbackVersion: Invalid or no callback version specified
CallbackDescriptor: Invalid or no callback descriptor specified
NetworkId: Invalid or no network id specified. Or, no privileges to specify a callback id.

Additional Notes:

The "Super Administrator" role may specify a callback either at the global scale or for any network.
The "Super Delegate" role may specify a callback for any assigned network.
The "Network Administrator" role may specify a callback for his or her own network.

Command Line Example

curl -v --insecure \
-H 'Accept: application/vnd.compendium.blog;version=2,application/json'  \
--user 'username:NxxJSBXNSS3QiaBvQgOFIfG9itGJrr2cENL7xJsq'  \
-d 'EventName=Posts.Approve.Success.Ping'  \
-d 'CallbackVersion=1' -d 'CallbackDescriptor=%7B%22CallbackUrl%22+%3A+%22https%3A%2F%2Fcallback.example.com%2Fmessage%2Fping%22%7D'  \
-d 'NetworkId=42ad5e24-f73c-4a99-9193-87dbac096822' \
 https://api.test.compendiumblog.com/app/callback

Compendium Documentation

Help