Pearson
Always Learning

This page describes the steps involved in receiving and processing an event from LearningStudio:

  1. LearningStudio Sends You An Event
  2. You Acknowledge the Event
  3. You Use the Event

LearningStudio Sends You an Event

LearningStudio sends events to the URL indicated when you create a subscription. This URL must be publicly accessible over ports 80 and 443 and support HTTPS. LearningStudio sends the event as follows:

Request

POST {subscriptionCallbackUrl}

Name Description Valid Values
{subscriptionCallbackUrl} The url specified at subscription creation URI

Request Header

Content-Type: application/x-www-form-urlencoded; charset=US-ASCII

Request Body

DELIVERY-ATTEMPT-ID={deliveryAttemptId}&MESSAGE-ID={messageId}&MESSAGE-TYPE={messageType}&AUTHORIZATION={authorization}&PAYLOAD={payload}&PAYLOAD-CONTENT-TYPE={payloadContentType}

Request Body Parameters

Name Description Valid Values
deliveryAttemptId The ID of the delivery attempt for the message. This value matches the messageId, and it may be removed at a future date. It was previously used as a unique identifier for repeated delivery attempts. GUID
messageId The ID of the message being delivered. If LearningStudio must attempt to deliver a message multiple times for any reason, this ID will remain constant across attempts. Note, this is different from the {eventId} that LearningStudio includes in the event payload. See the event contracts for more on that identifier. GUID
messageType The event type - e.g. a New Grade Event or Thread Response Event. These are specified in the event contracts. Any
authorization The data to use for verifying the authenticity of this event. Any
payload The JSON-encoded event payload. Any
payloadContentType The content-type of the payload Any

You Acknowledge the Event

When your web server receives an event, you must reply with a HTTP status code to acknowledge the event with an optional response body. The table below indicates which status codes should be used in various situations. Responses must be received within 10 seconds to prevent the message from being requeued.

HTTP Status Code Description Action We'll Take
200 Message received and accepted successfully. Dequeue message
201 Message received and created successfully. Dequeue message
412 Message was not consumed. Do not resend. Dequeue message
416 Message was not consumed. Prevent future messages. Dequeue message and delete subscription
Other/None Message was not consumed. Deliver again later. Requeue Message

Delivery Attempts

The first failed delivery of a message with an "Other" status code is reattempted a few seconds later. Each subsequent failure results in a 5% increase in the delay for the next delivery attempt. This pattern repeats until the maximum number of failures for delivery to a subscription is met. The maximum delivery attempts in the production environment is 500 resulting in a 72-hour retry window.

Message Delays

The delay on delivery reattempts is designed to prevent an accidental Denial of Service attack on your system. Many failing parallel messages can result in a large queue of messages to iterate. All messages destined for a subscription are placed in this queue, so even the successful messages will be delayed by the size of the queue when excessive failures have taken place.

Duplicate Delivery

Subscriptions are guaranteed at least one delivery for each message, and a subscription's callback URL is expected to be idempotent. This means your URL/application may receive a single message more than once and should respond consistently. This may require recognizing a duplicate MESSAGE-ID during the delivery window.

For example, if the system sends you the same message more than once, even if you responded with a 200 the first time, you should still response with a 200 and simply drop the message if you previously acted on it or no longer need it. Responding with no code or an error code could inadvertently unsubscribe you (see table above).

You Use the Event

When we deliver an event to you, we include an authorization parameter. This contains a string in the format {principal_id}|{timestamp}|{CMAC}, where:

  • principal_id is the identifier for your principal (associated with the subscription).
  • timestamp is an ISO8601 string representation of a date/time within 5 minutes of "now"
  • CMAC is the 128-bit CMAC digest of the bytes of
    {timestamp}{MESSAGE-ID}{MESSAGE-TYPE}{PAYLOAD-CONTENT-TYPE}{PAYLOAD}

Your application should re-calculate the 128-bit CMAC digest using the parameters from the event body, in order to verify the authenticity of the event. Though the message payload is not encrypted, verifying the authenticity of the message is important so you know for sure the message came from LearningStudio. This step-by-step guide gives detailed instructions on how to perform this check.

Once you’ve verified the authenticity of this event, your application can parse the JSON payload parameter and utilize the information it contains, generally by saving it in a secure database for future processing, or triggering other workflows within your application. The payload for each event is described in the Event Contract. See Event Contracts for more information.

2617 reads
Always Learning
Pearson