★ Webhooks
The support team of aNewSpring can set up webhooks to send a POST request to a URL of an external system. These webhooks contain information about the learner and the results of a course or activity. (There are examples below.)
Not a developer? There is also an article with a simplified explanation.
The format of the message can be either JSON (application/json) or XML (text/xml). The encoding is UTF-8.
To be able to determine whether a message is indeed sent from the aNewSpring platform, it is possible to configure a secret code. All messages will then contain an X-WebHook-Signature header that contains a Base64 encoded HMAC-SHA1 of the message and the secret.
An administrator of the learning environment (who also has the tenant role) can request us to set up the webhooks by sending an email to support@anewspring.com.
We need the following information:
- The URL to which we should send webhooks.
- Your preference of the message format (JSON or XML).
- A secret code, if you want us to send the X-WebHook-Signature header.
- If you want us to "prettify" the message, by making it easier to read for human eyes.
If the URL to which we send the message does not respond within 10 seconds OR if it doesn't return a status 200, 201, 202 or 204, we will try to deliver the message 10 more times, with an increasing interval (of 10 seconds to 16 hours).
It is important to only send us an error code if it would be useful for us to try sending the message again, so if the error is (or might be) temporary.
You don't have to send an error code if, for example, the user or course doesn't exist on the side of the external system or if a certain webhook type is not supported.
Each message contains a field that indicates which webhook was triggered. This field is called event in a JSON message and type in an XML message. There is an overview of possible webhooks below.
Each message also contains a field created which shows the original date of when the webhook was created. When we retry to send a message (because it couldn't be delivered or resulted in an error), this date will not change.
Overview of webhooks
These are the webhooks that we currently send. It is not possible for us to configure which ones should be sent, so we will send them all. It is then up to your external system to decide if the message is relevant.
CourseActivated
This webhook is sent when a learner starts a course (or when an administrator manually changes the subscription status from new to active).
Example of a JSON message:
{ "created": "2014-09-01T12:00:00.000Z", "event": "CourseActivated", "id": "5db1cc3b-4306-4689-91e4-def0bff0e58d", "user": { "course": { "id": "prince2", "name": "Prince 2", "uid": "a62b0836-7682-11eb-b67e-06575dd7e8c5" }, "id": "jwatson", "name": "John Watson", "uid": "c21f7c68-7682-11eb-b67e-06575dd7e8c5" } }
Example of an XML message:
<event id="5db1cc3b-4306-4689-91e4-def0bff0e58d" type="CourseActivated" created="2014-09-01T12:00:00.000Z"> <user id="jwatson" uid="c21f7c68-7682-11eb-b67e-06575dd7e8c5" name="John Watson"> <course id="prince2" uid="a62b0836-7682-11eb-b67e-06575dd7e8c5" name="Prince 2"/> </user> </event>
CoursePartCompleted
This webhook is sent after a learner completes a course activity (these don't include MemoTraining and extra practices).
Example of JSON message:
{ "created": "2014-09-01T12:00:00.000Z", "event": "CoursePartCompleted", "id": "31500949-6420-468d-91e4-def0bff0e58d", "user": { "course": { "id": "prince2", "name": "Prince 2", "part": { "attempt": { "attemptNr": -1, "completeDate": "2014-09-01", "completeDateTime": "2014-09-01T13:25:03Z", "completed": true, "passed": true, "progress": "2/2", "score": "10.0", "startDate": "2014-09-01", "startDateTime": "2014-09-01T13:20:41Z", "terms": [{ "maxScore": 3, "name": "Term 1", "score": 1, "threshold": 2 }] }, "id": "assessment1", "name": "Assessment 1", "type": "Assessment", "uid": "1807abf8-f34b-404d-8bb3-d6b8fd5ffb27" }, "uid": "a62b0836-7682-11eb-b67e-06575dd7e8c5" }, "id": "jwatson", "name": "John Watson", "uid": "c21f7c68-7682-11eb-b67e-06575dd7e8c5" } }
Example of an XML message:
<event id="31500949-6420-468d-91e4-def0bff0e58d" type="CoursePartCompleted" created="2014-09-01T12:00:00.000Z"> <user id="jwatson" uid="c21f7c68-7682-11eb-b67e-06575dd7e8c5" name="John Watson"> <course id="prince2" uid="a62b0836-7682-11eb-b67e-06575dd7e8c5" name="Prince 2"> <part id="assessment1" uid="1807abf8-f34b-404d-8bb3-d6b8fd5ffb27" name="Assessment 1" type="Assessment"> <attempt attemptNr="-1"> <startDate>2014-09-01</startDate> <startDateTime>2014-09-01T13:20:41Z</startDateTime> <completed>true</completed> <completeDate>2014-09-01</completeDate> <completeDateTime>2014-09-01T13:25:03Z</completeDateTime> <progress>2/2</progress> <score>10.0</score> <passed>true</passed> <terms> <term name="Term 1"> <maxScore>3</maxScore> <score>1</score> <threshold>2</threshold> </term> </terms> <criteria/> </attempt> </part> </course> </user> </event>
CourseCompleted
This webhook is sent after a learner completes an activity that is selected as the Course completing activity in the template settings.
The parameter grade can show the score of the activity selected at Base course grade on.
The parameter passed will be true or false if the activity selected at Base course grade on has a threshold. Otherwise this will be null .
The activity that is selected at Base course grade on needs to be completed before the Course completing activity or you need to select the same activity for both settings.
Please note: At the same moment that this webhook is sent, aNewSpring will also send a webhook CoursePartCompleted that partly contains the same information. The information in the webhook indicates if it was sent because of CourseCompleted or CoursePartCompleted.
Example of a JSON message:
{ "created": "2014-09-01T12:00:00.000Z", "event": "CourseCompleted", "id": "5db1cc3b-4306-4689-9eae-971c205c2c10", "user": { "course": { "id": "prince2", "name": "Prince 2", "grade": "10.0", "passed": true, "uid": "a62b0836-7682-11eb-b67e-06575dd7e8c5" }, "id": "jwatson", "name": "John Watson", "uid": "c21f7c68-7682-11eb-b67e-06575dd7e8c5" } }
Example of an XML message:
<event id="5db1cc3b-4306-4689-9eae-971c205c2c10" type="CourseCompleted" created="2014-09-01T12:00:00.000Z"> <user id="jwatson" uid="c21f7c68-7682-11eb-b67e-06575dd7e8c5" name="John Watson"> <course id="prince2" uid="a62b0836-7682-11eb-b67e-06575dd7e8c5" name="Prince 2"> <grade>10.0</grade> <passed>true</passed> </course> </user> </event>
CourseAdded
This webhook is sent when a learner is subscribed for a course.
Example of a JSON message:
{ "created": "2014-09-01T12:00:00.000Z", "event": "CourseAdded", "id": "5db1cc3b-4306-4689-91e4-def0bff0e58d", "user": { "course": { "id": "prince2", "name": "Prince 2", "uid": "a62b0836-7682-11eb-b67e-06575dd7e8c5" }, "id": "jwatson", "name": "John Watson", "uid": "c21f7c68-7682-11eb-b67e-06575dd7e8c5" } }
Example of an XML message:
<event id="5db1cc3b-4306-4689-91e4-def0bff0e58d" type="CourseAdded" created="2014-09-01T12:00:00.000Z"> <user id="jwatson" uid="c21f7c68-7682-11eb-b67e-06575dd7e8c5" name="John Watson"> <course id="prince2" uid="a62b0836-7682-11eb-b67e-06575dd7e8c5" name="Prince 2"/> </user> </event>
CourseDeleted
This webhook is sent when the course subscription of a learner is deleted.
Example of a JSON message:
{ "created": "2014-09-01T12:00:00.000Z", "event": "CourseDeleted", "id": "5db1cc3b-4306-4689-91e4-def0bff0e58d", "user": { "course": { "id": "prince2", "name": "Prince 2", "uid": "a62b0836-7682-11eb-b67e-06575dd7e8c5" }, "id": "jwatson", "name": "John Watson", "uid": "c21f7c68-7682-11eb-b67e-06575dd7e8c5" } }
Example of an XML message:
<event id="5db1cc3b-4306-4689-91e4-def0bff0e58d" type="CourseDeleted" created="2014-09-01T12:00:00.000Z"> <user id="jwatson" uid="c21f7c68-7682-11eb-b67e-06575dd7e8c5" name="John Watson"> <course id="prince2" uid="a62b0836-7682-11eb-b67e-06575dd7e8c5" name="Prince 2"/> </user> </event>