Pearson
Always Learning

In order to create a subscription, you must send an HTTP POST to our system, indicating the message type to which your application wants to subscribe, as described on this page. You may also Retrieve your Existing Subscriptions, or Delete an Existing Subscription.

Resource URLs

POST  https://prospero.ecollege.com/v1/subscription

Request Headers

Name Description Required?
Authorization Include the Authorization header (including signature token) as described in Subscription API Authentication. See below for how to create the token base string for Create requests. Yes
Content-Type Only use HTML Form Encoding, the only valid value is:
application/x-www-form-urlencoded; charset=US-ASCII
Yes

Request Body Format

CALLBACK-URL={callbackUrl}&TAGS={tags}&MESSAGE-TYPE={messageType}

Request Body Parameter Descriptions

Here is the description of the parameters used above. Note that each value must be URL-encoded. The parameter values need not be.

Name Description Valid Values
callbackUrl The URL to which LearningStudio should deliver events for this subscription Fully Qualified URL
tags A comma-separated list of context tags to filter by. For example:
UserId:12345,CourseId:9884a84
Valid Tags
messageType The message type to subscribe to. The message type ID is found in the Event Contract descriptions. You should have a distinct subscription for each new message type. Valid Type

Example Request Body

CALLBACK-URL=http%3A%2F%2Fexample.com%2Freceive%2Fpdn.test&TAGS=UserId%3AJohnDoe&MESSAGE-TYPE=pearson.ls.gradebook.grade.created

Authentication Token Base String

The signature token base string for Create Subscription requests is made up of the values you send in the request body. You only use the unencoded values, and concatenate them together with no delimiter. While the order of parameters request body does not matter, the values for the token base string must be in this order:

  • CALLBACK-URL
  • TAGS
  • MESSAGE-TYPE

For the example request body above, the base string would be:

http://example.com/receive/pdn.testUserId:JohnDoepearson.ls.gradebook.grade.created

Proceed by prefixing it with the timestamp and creating the hash , as described in the Authentication process.

Example Response Body Format

{
  "subscription": {
      "id": "{subscriptionId}",
      "principal_id": "subscriptionPrincipalId}",
      "callback_url": "{subscriptionCallbackUrl}",
      "wsdl_uri": "{subscriptionWsdlUri}",
      "queue_name": "{subscriptionQueueName}",
      "date_created": "{subscriptionDateCreated}",
      "date_cancelled": "{subscriptionDateCancelled}",
      "tags": [
        {
          "tag": {
          "id": "{tagid}",
          "type": "{tagMessageType}",
          "value": "{tagValue}"
        }
      }
    ]
  }
}

Response Body Parameter Descriptions

Name Description Valid Values
subscriptionId The ID assigned to the subscription Any
subscriptionPrincipalId The ID for the principal holding this subscription Principal ID
subscriptionCallbackUrl The callback URL for this subscription URI
subscriptionWsdlUri If applicable, the WSDL URI for this subscription URI
subscriptionQueueName The queue managing this subscription Any
subscriptionDateCreated The creation date of this subscription Date
subscriptionDateCancelled The cancellation data of this subscription. Blank if not cancelled. Date
tagId The identifier for the tag Any
tagMessageType The type of filter applied by the tag Any
tagValue The value of the filter applied by the tag Any

Example Response

{
  "subscription" : {
    "id" : "00000cbd-f51e-3fcf-aab2944f0dfa96f1",
    "principal_id" : "PDNTEST",
    "callback_url" : "http://example.com/receive/pdn.test",
    "wsdl_uri" : "",
    "queue_name" : "Sub-00000cbd-f51e-3fcf-aab2-944f0dfa96f1",
    "date_created" : "2014-02-11T17:07:54Z",
    "date_cancelled" : "",
    "tags" : [
      {
        "tag" : {
          "id" : "MessageType:pearson.ls.gradebook.grade.created",
          "type" : "MessageType",
          "value" : "pearson.ls.gradebook.grade.created"
        }
      },
      {
        "tag" : {
          "id" : "UserId:012345678",
          "type" : "UserId",
          "value" : "012345678"
        }
      }
    ]
  }
}
2197 reads
Always Learning
Pearson