Get notified when a learner completes Go1 content via the Enrolment Update webhook

Overview

This article explores how to utilise the Enrolment Update Webhook to get notified when a learner completes Go1 content. This method of tracking content completions allows you need to receive near real-time completion events from Go1 (a payload is sent for any user that completes a learning object), and to record these events in your application.

We recommend implementing this solution to track learner completions if you are, surfacing Go1 content within your application via authenticated links, or if you are using our SCORM packages to track learning - you may wish to implement this webhook as a catch-all to ensure the accurate capture of completion events.

How it works

To successfully set up and utilise the Enrolment Update webhook, we'll touch on the following three steps:

1. Creating the enrolment_update webhook
2. Receiving enrolment_update event payloads
3. Actioning the enrolment updates in your application

These steps will be outlined in greater detail within the Implementation Steps section of this article below.

How the Enrolment Update webhook works

To first understand how the enrolment update works, we'll briefly touch on the concept of Enrolments within the Go1 ecosystem. An Enrolment is an event that is recorded by Go1 whenever a user begins a new learning object within the Go1 Library (a learning object or LO is any learning resource within the Go1 library, eg. a course or video). Each created enrolment has a status associated with it of in-progress or complete, which records the users progress through the learning object.

A user can be enrolled in a learning object themselves by simply starting a new learning object resource. Or, they could be enrolled by another actor, for example by an Admin or Manager user in the Go1 web application. There is a separate webhook event that is fired whenever a learner enrols into a new learning object - this is the enrolment_create event, you can learn more about his event via our Webhook API Reference.

In this instance, we are interested in when a user progresses and completes their enrolment in the learning object - this is where the enrolment_update webhook comes in.

The enrolment_update event will trigger in two different circumstances as described below:

• (1) Whenever a user completes a learning object. In other words, the event will fire when a user's enrolment status in a learning object changes from in-progress to complete.
• (2) Whenever a user makes notable progress within a learning object, or in other words, when a users enrolment details change but the enrolment is still in an in-progress state. An in-progress event is typically sent for our course type learning object, which contains multiple resources, and the users have progressed successfully through a resource but not completed the entire course.

Below is an example payload for the enrolment_update event for a completed enrolment:

{
    "type": "enrolment.update",
    "fired_at": "2020-08-11T07:58:20+0000",
    "data": {
        "id": "24107698",
        "user_id": "3940255",
        "lo_id": "16708031",
        "lo_type": "video",
        "taken_instance_id": "1975286",
        "status": "completed",
        "pass": "1",
        "result": "100",
        "assessments": null,
        "created_time": "2020-08-11T07:58:15+0000",
        "completed_time": "2020-08-11T07:58:20+0000",
        "actor_id": 3940255,
        "award": null
    },
    "original": {
        "id": "24107698",
        "user_id": "3940255",
        "lo_id": "16708031",
        "lo_type": null,
        "taken_instance_id": "1975286",
        "status": "in-progress",
        "pass": "0",
        "result": "0",
        "assessments": null,
        "created_time": "2020-08-11 07:58:15",
        "completed_time": null,
        "actor_id": null,
        "award": null
    }
}

Note that the payload contains the original state of the enrolment (before the update), and the new state of the enrolment (after the update has occurred). We'll discuss the attributes received in this payload in greater detail within the implementation steps below.

Preparation

Before setting up a webhook, you will need a establish a service in your application that can receive the webhook payload from Go1. As part of this process, your service will need a URL that will be used as the location for Go1 to send webhook events to. This URL location will be configured when you initially create the webhook via the Go1 API. We will discuss this further in the implementation steps below.

Implementation steps

Step 1. Creating the enrolment_update webhook

To create the enrolment_update webhook, make a POST request to the /v2/webhooks endpoint, specifying the following values in the body:

• enrolment_update, set this value to true, this tells Go1 which events this webhook would like to receive (you can enable multiple webhook events via this single webhook).
• URL, the URL location you wish Go1 to send event notifications to - must be a valid URL.
• (optional) secret_key, a secret string of our choice, used for security purposes, learn more here.

Here is an example request (see the API Reference: POST /v2/webhooks):

A successful response will return the created webhook ID. The webhook ID can be used later to view, update or delete the webhook - see the Webhook API reference to learn more about these functions.

With the webhook created, you are now ready to receive payload events to the URL you have configured. Note that this created webhook will only apply to the customer portal that you created the webhook for (using the customer access token), if you are working with multiple customer portals, you will need to establish this webhook for each portal.

Step 2. Receiving the enrolment_update event payloads

When any user completes a Go1 learning object, ie. they progress their enrolment of a learning object from in-progress to complete, the enrolment_update event will fire a payload.

Within the payload, make note of the following attributes:

• type: enrolment.update, is the type of event fired. Remember, a single webhook may have multiple events enabled.
• data, is the updated enrolment that triggered the notification.
• original, is the previous enrolment event.
• id, is the id of the Enrolment object record that was created when the user began the Learning Object.
• user_id, is the Go1 id of the user that the enrolment record belongs to (the user who completed the learning).
• lo_id, is the id of the Learning Object that the user has completed.
• status, is the learner’s previous/current progress within the learning object. All new enrolments enter an in-progress state by default, and you are likely to see the original status as in-progress, and the data status as complete. Keep in mind that there are scenario’s where the status between the data object and the original is the same due to the enrolment update occurring within a course that has sub-modules.
• pass, if the learner has passed or failed the completed the learning object (where there is an assessment component), this will be provided as a boolean.
• result, is the outcome for the enrolled learner for the completed learning object as a percentage out of 100.
• taken_instance_id, is the related Go1 portal id that the learner conducted the learning in for the provided enrolment update. Unlikely to be of concern if configuring a single webhook for each Go1 customer portal you connect. If you are creating multiple webhooks for customers and sending them to a single destination within your application you will need to reference this id to determine which related Go1 portal the enrolment event occurred in.
• actor_id, is the Go1 user id that triggered the event. Will typically match the user_id, however, can also differ if a Learning Admin changes an enrolment state on behalf of another user. Only of concern if you are implementing the enrolment.delete webhook event.
  

Step 3. Actioning the enrolment updates in your application

The Enrolment Update event can be used in various scenarios - such as tracking and recording learner completions through Go1 content within your application.

To map the enrolment update event to your application, you'll need to ensure that you have context of the following points of data:

(1) The user who has completed the learning

The webhook payload provides only the Go1 User ID, you'll need to implement a way to map the payload to the correct user in your application. How you map this to the user depends on your integration use-case, specifically how users are being created and getting access to Go1 content.

If you are creating users via our API, you should be able to capture and map the Go1 user-id at the point of creation, or you could implement a separate service to handle this using our user_create webhook event (which fires a payload with the user's details when a new user is created).

An alternate solution is to perform a secondary API request using the Go1 User Id to lookup the user's email address and map this completion via a matching email address in your application. To do this you make a GET request to /v2/users/<user-id>. This scenario is only viable if the user's email address that is created in Go1 matches the email address stored in your application.

(2) The learning object that has been completed

The webhook payload provides the Go1 learning object id (LO-ID) to identify the content that the user has completed. You will need to ensure that your application has context of the LO-ID and that you can map that to a matching object in your application to record the user's completion against.

If you have surfaced Go1 content in your application via our documented discovery concept, you should have been able to store the learning object ID in your application during this phase of work. If you require additional context of the learning object at this stage, you can query the Learning Object Details endpoint to identify and obtain the learning object details (ie. title, author, description, etc).

With these mapping principles arranged, you should now be able to take the payload, containing the Go1 User ID, the LO-ID and the enrolment completion status, and record this against the users learning in your application.

Learn more

• API Reference - POST /v2/webhooks
• Full API Reference