Registration postbacks (commonly called “web hooks” in today’s terms) are a mechanism that allows SCORM Cloud to send registration updates directly from our system to yours. Postbacks are essentially the only way to reliably get near-real-time updates about registration state.
When implementing postbacks, we recommend using the registration service’s TestRegistrationPostback method to test your postback implementation. This API call will generate dummy data and POST it to the endpoint you specify.
See Postback Settings below for a description of the postback settings.
We consider 3xx status codes (like a 302 redirect) to be successful, as we can’t follow HTTP redirects for POST requests as per the spec. 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
urlis configured to be an HTTP URL and your system tries to redirect to HTTPS.
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 testRegistrationPostUrl 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).
To perform a postback, our system builds the registration state using the exact same format as GetRegistrationProgress and sends that data to your system – see Format (authtype) below for how that data is sent to your system.
As stated above, postback settings in all cases offer the same parameters:
The HTTP/HTTPS URL to which results data will be POSTed. We strongly recommend using HTTPS.
An optional login name that will be sent to the postback URL (see below for format information)
An optional login password that will be sent to the postback URL (see below)
httpbasic), this parameter controls the format of how we send the getRegistrationResult data to your system. We recommend using
We recommend using the form authtype unless httpbasic is required.
If the authtype is set to form (the recommended) or left blank, we will send a request to your endpoint with:
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
The body of that request will contain up to three URL-encoded parameters, as per that content type:
passwordparameter, if both were set, and
dataparameter containing the URL-encoded
This request type ends up being the same as a simple HTML form submission –which makes it convenient for development. In PHP, these variables can be accessed via
$_REQUEST, for example.
If the authtype is set to httpbasic, we will send a request to your endpoint with:
Content-Type: application/json; charset=UTF-8
If the username and password are provided, they will be sent via typical HTTP basic auth in the request. That is, the username and password will be concatenated together (separated by a colon), then base64-encoded, and then put in the Authorization header. For example:
Authorization: Basic dGVzdHVzZXJuYW1lOnRlc3RwYXNzd29yZA==
This is the authorization header for the username
testpassword, the same parameters as above in the form
example. (That is, the above header is
base64("testusername:testpassword") in pseudocode.)
The body of the request will be the URL-encoded