Configuring Skillable Lab Webhooks

Using Webhooks is an efficient way of receiving information from the Skillable platforms. Studio Webhooks can be configured to automatically send data when there is any change in the status of a Lab instance lifecycle as well as a change to a lab assignment or the Lab Profile itself.

The following sections will help guide you to effectively set up and use Webhooks in Skillable Studio.

Best Practices

Webhooks, like API endpoints, provide an easy method of retrieving data or notifications of events. Follow these best practices to get the most of your webhook configurations.

Webhooks, unlike APIs, do not require a request. Configure the webhook to activate on the most appropriate event for the best results.
Always ensure that the receiving URL is properly configured and available. If you receive an error when you navigate to the receiving URL you will not receive the webhook payload.
Be careful when configuring the Delay, Timeout and Maximum Retries as this can cause confusion when multiple webhooks are configured or triggered at the same time.

Add a Skillable Studio Webhook

In Skillable Studio, Webhooks are tied directly to the API Consumer to which Lab Profiles are published to, enabling you to configure different webhooks for different labs in multiple scenarios. You can set up one or more Skillable Studio Webhooks for each API Consumer directly from the API Consumer details page in Studio.

From the Site Administration page on the Integration tile, select API Consumers.
Search for the specific API Consumer that you wish to configure Webhooks for.
To open the API Consumer details page, select the API Consumer name, or , from the list.
In order to add a new Webhook, scroll down the Webhooks section, beneath the LTI section, and select + Add Webhook.
Section availability
If this section is not available to you, please open a support ticket to have additional permissions aaded to your user account to be able to configure webhooks.
Use the next section Setting up your Studio Webhook to complete the fields in the Add Webhook dialog.
To save your webhook select OK.
Example Webhook configuration:

Setting up your Studio Webhook

Once you have opened the Add Webhook dialog there are a number of fields that can be configured. The following table describes each field in detail.

Field	Details
Name	Enter the name of the webhook.
Event	Select the required to trigger the return of the information you require. (See the list of the events from the Skillable Studio Webhook Events section)
Verb	Different types of verbs are used to perform different types of actions. • GET: Use the GET verb to obtain data. • POST: Use the POST verb to add new data. • DELETE: Use the DELETE verb to delete data. • PUT: Use the PUT verb to modify data.
URL	Input a webhook URL where the Webhook response is sent when the configured platform event occurs. NOTE: Any lab replacement token can also be added to the URL surrounded by {}. For example:The lab instance ID will be injected into URL using the replacement value {id}. Example: `https://myexternalsite.com/labinstance/changed/{id}`
Headers	Enter HTTP Header details to send additional information with the HTTP request or response. NOTES: • Headers should be entered in name=value format, with each header on a new line. • It is recommended to add an authorization header in order to secure your webhook. • If Basic Authentication is required for the webhook in the header field enter `Authorization=Basic <Base64 URL Safe version of the Username:Password>` Assuming a username of `Webhookuser` and a password of `webhookpassword` the Base64 URL Safe string of `Webhookuser:webhookpassword` is `V2ViaG9va3VzZXI6d2ViaG9va3Bhc3N3b3Jk`. In the header field the full entry would be `Authorization=Basic V2ViaG9va3VzZXI6d2ViaG9va3Bhc3N3b3Jk`. Note: To help with converting the username and password there are many available tools including Cyber Chef
Send Lab Details as Content Body	Select this field if you want the content body to contain JSON-formatted information about the lab instance (see note below). Selecting this field supercedes the Content field.
Content	Enter the optional content body of the webhook request. Note: Contact Skillable support for help on how to configure this field.
Enabled	Select this field to enable this webhook.
Blocking	Select this field to allow you to block further triggering of events and other webhooks until this webhook execution completes. Note: If a webhook fails and is set to blocking, the next event in the life cycle will not begin until the webhook succeeds or fails. If the webhook has retries enabled, Skillable Studio will retry up to 5 times before moving onto the next life cycle event.
Delay	Enter an optional delay before the webhook is triggered.
Timeout	Enter the amount of time, in seconds, to wait for the webhook request to complete, before timing out.
Retries	Set the maximum number of times the webhook will be called in the event of an error response. Note: The time between retries is 1 second for the 1st retry, 2 seconds for the 2nd retry, 3 seconds for the 3rd retry, 4 seconds for the 4th retry, and 5 seconds for the 5th retry. Skillable Studio will only retry 5 times.
Error Action	Select the action to take in the event that a webhook returns an error response. • Log: logs the error on the user's lab instance details page. • Send Notification to User: sends a notification to the user's lab instance. • End Lab: ends the user's lab instance.

Sending Lab Details as the Content Body JSON

When selecting the Send Lab Details as Content Body option, the content body of your webhook response will contain JSON-formatted information about the lab instance including the following fields.

Field	Details
Id	The ID of the lab instance.
UserId	The ID used to identify the user in the Skillable Studio system.
UserExternalId	The ID used to identify the user in your external system.
UserFirstName	The user's first name.
UserLastName	The user's last name.
LabProfileId	The system ID of the lab profile.
LabProfileName	The name of the lab profile.
LabProfileNumber	The text ID of the lab profile.
LabSeriesId	The ID of the lab series.
LabSeriesName	The name of the lab series.
ClassId	The ID you use to identify the associated class in the Skillable Studio system.
ClassExternalId	The ID you use to identify the associated class in your external system.
ClassName	The name of the class the lab instance is associated with.
Start	When the lab was started (in Unix epoch time).
End	When the lab ended (in Unix epoch time).
Expires	When the lab expires (in Unix epoch time).
LastActivity	When student activity was last detected (in Unix epoch time).
LastSave	When the lab was last saved (in Unix epoch time).
State	The state of the lab instance. Possible values: • 0: Off • 10: Provisioning Storage • 20: Building • 25: Building (Displayable) • 30: Starting • 40: Running • 50: Saving • 60: Saved • 70: Resuming • 80: Creating Snapshot • 90: Applying Snapshot • 100: Updating Lab Profile • 110: Tearing Down • 120: Cloning • 130: Creating As Clone • 140: Moving (While Running) • 150: Moving (While Saved) • 160: Creating New Lab Profile • 170: Scoring • -1: Scheduled
CompletionStatus	The student's completion status. Possible values: • 0: Scheduled • 1: Cancelled • 2: Not Started • 3: Incomplete • 4: Complete • 10: Storage Provisioning Failed • 20: Lab Creation Failed • 30: Resume Failed • 40: Save Failed • 50: Submitted For Grading • 60: Grading In Progress
CustomData	An optional parameter that can be used for tagging the lab instance with custom data
ExamPassed	Indicates whether the user passed the lab. Will only be set if the lab has activities which have been scored.
ExamScore	Indicates the lab score. Will only be set if the lab has activities which have been scored.
ExamMaxPossibleScore	Indicates the maximum possible score of the lab. Will only be set if the lab has activities which have been scored.
ExamPassingScore	Indicates the minimum score required to pass the lab. Will only be set if the lab has activities which have been scored.

This is an example of a JSON-formatted content-body containing the results of selecting the Send Lab Details as Content Body field.

{
    "Id": 998592321,  
    "UserId": 5023932,  
    "UserExternalId": "Example.User",  
    "UserFirstName": "Example",  
    "UserLastName": "User",  
    "LabProfileId": 19376,  
    "LabProfileName": "Example Lab",  
    "LabProfileNumber": "ABC",  
    "LabSeriesId": 10296,  
    "LabSeriesName": "Example Series",  
    "ClassId": null,  
    "ClassExternalId": null,  
    "ClassName": null,  
    "Start": 1671565852,  
    "End": null,  
    "Expires": 1671587452,  
    "LastActivity": null,  
    "LastSave": null,  
    "State": 20,  
    "CompletionStatus": 2,  
    "CustomData": null,  
    "ExamPassed": null,  
    "ExamScore": null,  
    "ExamMaxPossibleScore": 10,  
    "ExamPassingScore": 7  
}

Skillable Studio Webhook Events

Webhooks are an event-driven activity. This means that virtually any event or change in an application could be used to develop a Webhook. However, the list of possibilities could quickly become cumbersome. Therefore, Skillable has targeted the following specific events for webhooks and is always considering additions to this list.

Event	Description
Pre-Build	The lab components are being deployed, as well as any cloud resources.
Post-Build	The lab environment has been built, but components like virtual machines may still be starting.
First Displayable	All components of the lab are now running and the user can now interact with the lab.
Saving	The lab is in the process of being saved.
Saved	The lab is in a saved state and no longer active.
Resuming	The lab is resuming from a saved state.
Resumed	The lab has been resumed from a saved state and the user can interact with the lab again.
Scoring	The lab has begun the process of scoring. This triggers immediately when scoring is initiated in the lab, before platform scoring is performed. If the action is blocking, this will allow the action to complete before platform scoring occurs.
Scored	The lab has been scored. This triggers immediately after platform scoring completes. If the action is blocking, this will allow the action to complete before the lab is torn down or returned to a running state.
Tearing Down	The lab environment is being torn down.
Torn Down	The lab environment is fully torn down.
Transfer to User	The lab instance is transferred to another user from the lab instance.
Deferred Launch (New)	A new lab has been launched via a deferred launch page, as opposed to a direct Launch API.
Deferred Launch (Existing)	An existing lab has been launched via a deferred launch page, as opposed to a direct Launch API.
Deferred Resume	A lab has been resumed via a deferred launch page, as opposed to a direct Launch API.
Lab Assignment Created	A lab profile has been assigned to a user.
Lab Profile Changed	A lab profile has been changed. For example, a content edit or configuration change has been performed.

Lifecycle Events

Events in this list appear in Lab Instance lifecycle order except for Lab Assignment Created and Lab Profile Changed which can occur outside the Lab Instance Lifecycle.