Registration Postback Guide

Get Automatic Learner Progress Updates

The best way to ensure that your system stays up to date with the progress of your registrations is to leverage Registration Postbacks (we’ll use “postback” for short from here). With postbacks configured, SCORM Cloud will feed registration progress updates via HTTP POST requests to an endpoint in your system.


Postback Configuration Settings

Postbacks are represented in SCORM Cloud by a group of configuration settings. These settings will dictate the behaviors of the POST requests we send to your system, such as: where to send the requests (URL), in what format it should be sent, and if/how to authenticate the requests.

Let’s take a look at the postback configuration settings available to us:


ApiRollupRegistrationPostBackUrl

You may also see this referred to as postBack.url in some API endpoints.

The HTTP/HTTPS URL to which we’ll POST the registration data. We strongly recommend configuring an endpoint that supports HTTPS here.


ApiRollupRegistrationAuthType (default: form)

You may also see this referred to as postBack.authType in some API endpoints.

Determines the Content-Type header of the POST requests sent from SCORM Cloud, as well as the type of authentication used on the request. Options are:

form

  • Sent as: Content-Type: application/x-www-form-urlencoded; charset=UTF-8
  • The body of the postback will contain up to 3 URL-encoded parameters.
    • data - The URL-encoded JSON payload. This matches the JSON schema returned by GetRegistrationProgress
    • userName - The optional ApiRollupRegistrationAuthUser setting value. Provided to authenticate the request.
    • password - The optional ApiRollupRegistrationAuthPassword setting value. Provided to authenticate the request.
  • Matches semantics with a simple HTML form submission.

httpbasic

  • Sent as: Content-Type: application/json; charset=UTF-8
  • The body of the postback will be a JSON payload matching the JSON schema returned by GetRegistrationProgress.
  • If both the optional postback settings ApiRollupRegistrationAuthUser and ApiRollupRegistrationAuthPassword are set, these will be used to craft a typical HTTP basic auth header. As an example, that header would look like this: Authorization: Basic dGVzdHVzZXJuYW1lOnRlc3RwYXNzd29yZA==.


ApiRollupRegistrationAuthUser

You may also see this referred to as postBack.userName in some API endpoints.

An optional login name to be included in the POST requests. The ApiRollupRegistrationAuthType dictates how this setting will be included in the requests.


ApiRollupRegistrationAuthPassword

You may also see this referred to as postBack.password in some API endpoints.

An optional login password to be included in the POST requests. The ApiRollupRegistrationAuthType dictates how this setting will be included in the requests.


ApiRollupRegistrationFormat (default: course)

You may also see this referred to as postBack.resultsFormat in some API endpoints.

This setting configures the format of the JSON schema sent in the body of the POST request. More specifically, this setting dictates how much detail will be POSTed to your system. For most use cases the course level of detail will suffice. Take care to not request full detail unless you really need all the detail, as this is an expensive object to calculate and may add some latency to postback delivery. Options for this setting are:

course

Payload will match the JSON schema returned from GetRegistrationProgress with none of the optional detail flags turned on.

activity

Payload will match the JSON schema returned from GetRegistrationProgress with includeChildResults set to true

full

Payload will match the JSON schema returned from GetRegistrationProgress with all optional detail flags turn on: includeChildResults, includeInteractionsAndObjectives, and includeRuntime.


ApiRollupRegistrationIsJson (default: true)

You may also see this referred to as postBack.legacy in some API endpoints. This setting will determine if the body of the postback request will be sent in JSON, or the legacy XML format. This setting is largely a convenience for people migrating from our V1 API. For new integrations, you can largely disregard this.


Configuring Postbacks

Luckily, all of these configuration settings are easily managed via the SCORM Cloud V2 API. If you’re not familiar with how our configuration system is laid out, now would be a good time to checkout the configuration overview.

Postbacks fit nicely into the cascading configuration system. For instance, if you wish that all postbacks for an Application should go to the same URL, then you can set ApiRollupRegistrationPostBackUrl at the Application level. Doing so will make all registrations within that Application report progress to the provided URL. The JSON body you’d submit to any of the SetConfiguration endpoints would look like this:

{
  "settings": [
    {
      "settingId": "ApiRollupRegistrationPostBackUrl",
      "value": "https://example.com/webhooks/scorm_cloud"
    }
  ]
}

Note that with the above form, each setting has its own object in the settings array, and uses the fully qualified configuration system setting name.


In some API methods we also offer a convenience shorthand JSON object which can be provided at the time a resource is created. The shorthand JSON looks like this:

{
  "postBack": {
    "url": "https://example.com/webhooks/scorm_cloud",
    "authType": "FORM",
    "userName": "username",
    "password": "password",
    "resultsFormat": "COURSE"
  }
}


Now let’s break down the levels at which you can set postbacks, and the methods you can use to do so.

Registration

You can configure postbacks on a per-registration basis easily, and we provide a few ways to do so.

Course

You can configure postbacks at the course level using the configuration endpoints.

Note:
There is no shorthand available for this level. The postbackUrl that you can provide in the calls to import a course is NOT for Registration Postbacks. Instead it is to receive a notification that the course import is completed.

Application

You can configure postbacks at the application level using the configuration endpoints.

Dispatch

You may notice that the Dispatch resource does not currently have Configuration endpoints available. As such, the path for setting postback configuration is as follows:

Invitation

The Invitations resource also lacks Configuration endpoints. Postback configuration can be set with the following methods:


Testing Postbacks

We provide a convenient method allowing you to trigger a dummy postback payload to be sent from our system. This should be a big help during the development process. TestRegistrationPostback accepts the shorthand JSON postback configuration, and immediately sends a payload to your system.

Caution

We consider 3xx status codes (like a 302 redirect) to be successful, and we will not follow HTTP redirects for POST requests. Make sure your system isn’t returning a 301 or 302 redirect for your endpoint, as it likely isn’t processing the actual data if so. This is especially common if your ApiRollupRegistrationPostBackUrl is configured to be an HTTP URL and your system tries to redirect to HTTPS.


Retries and Error Handling

Postbacks were designed to be highly reliable. Our system uses a durable work queue built on top of Amazon Web Service’s Simple Queue Service (SQS).

When your system responds to our HTTP request, we consider any non-4xx and non-5xx status codes as success. Any response that has a 4xx or 5xx status code or any other general failure (like a connection timeout, DNS lookup failure, etc.) is treated as a failed request and will be retried later.

Note:
Postbacks sent via TestRegistrationPostback do not use the work queue and will not be retried.


We retry failed requests up to 70 times. After each unsuccessful attempt, we add a delay before the next retry. That delay follows an exponential backoff with jitter algorithm.

Specifically: we will always wait at least 1 second between attempts. We will wait a maximum of 15 minutes between attempts (an AWS SQS API limitation). Within those bounds, we will wait exponentially longer between attempts. This means that the first 5 retries will happen across the span of approximately 15-20 seconds. The remaining 60 retries will happen across the span of approximately 6-8 hours. After about 6-8 hours, our system gives up.

For a given registration, we only retry the most recently generated; postbacks don’t stack up for a single registration. Thus, when your system receives a postback successfully, it is always the latest registration state (not out-of-date data that failed earlier).