This page describes the steps involved in receiving and processing an event from LearningStudio:
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:
||The url specified at subscription creation||URI|
Content-Type: application/x-www-form-urlencoded; charset=US-ASCII
Request Body Parameters
||The ID of the delivery attempt for the message. This value matches the
||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
||The event type - e.g. a New Grade Event or Thread Response Event. These are specified in the event contracts.||Any|
||The data to use for verifying the authenticity of this event.||Any|
||The JSON-encoded event payload.||Any|
||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|
||Message received and accepted successfully.||Dequeue message|
||Message received and created successfully.||Dequeue message|
||Message was not consumed. Do not resend.||Dequeue message|
||Message was not consumed. Prevent future messages.||Dequeue message and delete subscription|
|Other/None||Message was not consumed. Deliver again later.||Requeue Message|
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.
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.
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_idis the identifier for your principal (associated with the subscription).
timestampis an ISO8601 string representation of a date/time within 5 minutes of "now"
CMACis the 128-bit CMAC digest of the bytes of
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.