Configuring Skillable Lab Webhooks
    • 11 Sep 2024
    • 8 Minutes to read

    Configuring Skillable Lab Webhooks


    Article summary

    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.

    1. From the Site Administration page on the Integration tile, select API Consumers.

      Admin API Consumers Highlighted

    2. Search for the specific API Consumer that you wish to configure Webhooks for.

    3. To open the API Consumer details page, select the API Consumer name, or Details button, from the list.

    4. 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.

      Add new Webhook Highlighted

    5. Use the next section Setting up your Studio Webhook to complete the fields in the Add Webhook dialog.

    6. To save your webhook select OK.

      Example Webhook configuration:

      Retrieve Score Full Webhook


    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.


    Was this article helpful?

    Changing your password will log you out immediately. Use the new password to log back in.
    First name must have atleast 2 characters. Numbers and special characters are not allowed.
    Last name must have atleast 1 characters. Numbers and special characters are not allowed.
    Enter a valid email
    Enter a valid password
    Your profile has been successfully updated.