Manage content updates via the content.update webhook (DEPRECATED)

The information on this page is now deprecated, along with the content.update webhook. A replacement webhook system is being released to support content changes, contact Go1 support for more information.

Get notified when Go1 content has been updated, so you can update the metadata presented for that course within your application.

Overview

This article explores how to utilise the Content Update Webhook to get notified and action new updates to the Go1 library. The Go1 library is continually evolving and being updated by our content providers in the following ways:

  • new content is added to the library
  • content is removed from the library
  • content has been changed/edited

The content_update webhook event is triggered whenever content that you can see within your Go1 portal changes. When these updates occur, if you have previously synced content to your application, it is your responsibility to handle the content updates in an elegant way to provide the best user experience for your customers and users. We'll provide some examples and best practices for how to action content updates in your application in greater detail in the implementation steps below.

Content material updates when working with Go1's SCORM files

If you have chosen to retrieve Go1 learning objects as SCORM files (see. Download and play content as SCORM), each piece of Go1 content has a 1:1 relationship with our SCORM wrapper package. The SCORM wrapper is simply a window to the content materials that reside on Go1's servers. This means that when content materials are updated by Go1 content providers, the changes will be automatically reflected through the existing SCORM files you have obtained from Go1, there is no need for you to resync SCORM packages. You are only required to update the content metadata if this is changed by the provider - eg. the title, description, images, etc.

How it works

To successfully set up and utilise the content update webhook, we'll walk through the following implementation steps below.

  1. Creating the content_update webhook
  2. Receiving the content_udpate event payloads
  3. Identifying the update that took place
  4. Actioning the update in your application

How the content update webhook works

The content_update webhook payload event is triggered whenever content within the entire Go1 library is updated. This includes new content added, content is removed, content is edited.

Whenever one of these actions happen across the entire library, Go1 will fire a payload to the configured webhook containing a list of lo-ids that have been affected.

Example payload:

{
    "type": "content_update",
    "fired_at": "2020-08-17T06:11:29+0000",
    "data": {
        "loIds": [
            22646286,
            22906633,
            22911740,
            23083834,
            23962354,
            23965684,
            23995342,
            24003022,
            24020976
        ]
    }
}

These notifications are ignorant of the content that you may have synced to your application. Additionally, these notifications are ignorant of the type of update that has occurred to the content. It could be that new content is now available, content metadata have been updated, or content has been removed entirely. The receiver must work out what actually happened to each learning object sent in the payload. We'll discuss this in greater detail in the implementation steps below.

Preparation

Before setting up the webhook, you will need a establish a URL in your application that can receive payloads from Go1 webhooks. This URL location will be configured when you initially create the webhook - see how this works below.

Implementation steps
Step 1. Creating the content_update webhook

To create the content_update webhook, make a POST request to the https://api.go1.com/v2/webhooks, specifying the following values in the body:

  • content_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:

curl --location --request POST 'https://api.go1.com/v2/webhooks' \
--header 'Authorization:<CUSTOMER_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "enrollment_create": false,
    "enrollment_delete": false,
    "enrollment_update": false,
    "lo_create": false,
    "lo_delete": false,
    "lo_update": false,
    "enabled": true,
    "secret_key": "",
    "url": "<YOUR LOCATION URL TO RECEIVE PAYLOADS FROM GO1>",
    "user_create": false,
    "user_delete": false,
    "user_update": false,
    "content_update": true,
    "content_decommission": false
}'

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.

Step 2. Receiving the content_udpate event payloads

When new content is added, content is removed or content is edited, Go1 will trigger a content_update event that will be sent to your configured webhook URL. The payload will contain a list of LO-ID (learning object ids) for the content that has been updated.

{
    "type": "content_update",
    "fired_at": "2021-03-31T00:35:29+0000",
    "data": {
        "loIds": [
            22646286,
            22906633,
            22911740,
            24020976
        ]
    }
}

Within the payload, make note of the following:

  • type: content_update, is the type of event that’s fired. Remember, a single webhook may have multiple events enabled.
  • loIds, is a list of the Learning Objects that have been updated. The content we provide updates for is universal across the entire Go1 library - meaning the updates you receive may be for content that your users do not have access to.
Step 3. Identifying the update that took place

You'll note that the content update payload does not specify what updates took place to the content. The payload will include a list of learning object id's - you will need to validate the type of update that took place.

To do this, you can query the Learning Object by passing in the LO-ID to the API via a GET request to /v2/learning-objects/<LO-ID>. The response from the API will help you determine what has happened to the learning object in question.

  • New Content - if the LO returns a success message and previously did not exist, you can determine this is new content in the library.
  • Removed Content - if the LO returns a 404, you can determine this is content that has been removed from the library.
  • Edited Content - if the LO is there, and had previous existed, you can determine the content has been updated.

Step 4. Actioning the update in your application

Ultimately how you choose to action these updates in your application is up to you. To provide the best user experience to your customers and users, we recommend the below actions:

  • If the content is new, consider notifying users that some new content is available, and creating a way for them to preview, and import this content.
  • If the content exists on your side and has been updated, consider re-fetching the content meta-data via a request to the /v2/learning-objects/<LO-ID> endpoint, and syncing the new meta-data to your platform to ensure you have the latest changes to the content meta-data. You may also want to notify customers of changes.
  • If the content has been removed, consider notifying your customers that the content has now been archived and will no longer be available. You could also introduce a method to automatically remove this content from your application if safe to do so. To ensure your users have ample notification of content removals, we recommend utilising the Content Decommisions webhook which will give a 60-day in advance warning of content that will be removed from the library.