Configuring Skillable Lab Webhooks
    • 18 Mar 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 configuratons.

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

    FieldDetails
    NameEnter the name of the webhook.
    EventSelect the required to trigger the return of the information you require. (See the list of the events from the Skillable Studio Webhook Events section)
    VerbDifferent 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.
    URLInput 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}
    HeadersEnter 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 BodySelect 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.
    ContentEnter the optional content body of the webhook request.
    Note: Contact Skillable support for help on how to configure this field.
    EnabledSelect this field to enable this webhook.
    BlockingSelect 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.
    DelayEnter an optional delay before the webhook is triggered.
    TimeoutEnter the amount of time, in seconds, to wait for the webhook request to complete, before timing out.
    RetriesSet 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 ActionSelect 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.

    FieldDetails
    IdThe ID of the lab instance.
    UserIdThe ID used to identify the user in the Skillable Studio system.
    UserExternalIdThe ID used to identify the user in your external system.
    UserFirstNameThe user's first name.
    UserLastNameThe user's last name.
    LabProfileIdThe system ID of the lab profile.
    LabProfileNameThe name of the lab profile.
    LabProfileNumberThe text ID of the lab profile.
    LabSeriesIdThe ID of the lab series.
    LabSeriesNameThe name of the lab series.
    ClassIdThe ID you use to identify the associated class in the Skillable Studio system.
    ClassExternalIdThe ID you use to identify the associated class in your external system.
    ClassNameThe name of the class the lab instance is associated with.
    StartWhen the lab was started (in Unix epoch time).
    EndWhen the lab ended (in Unix epoch time).
    ExpiresWhen the lab expires (in Unix epoch time).
    LastActivityWhen student activity was last detected (in Unix epoch time).
    LastSaveWhen the lab was last saved (in Unix epoch time).
    StateThe 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
    CompletionStatusThe 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
    CustomDataAn optional parameter that can be used for tagging the lab instance with custom data
    ExamPassedIndicates whether the user passed the lab. Will only be set if the lab has activities which have been scored.
    ExamScoreIndicates the lab score. Will only be set if the lab has activities which have been scored.
    ExamMaxPossibleScoreIndicates the maximum possible score of the lab. Will only be set if the lab has activities which have been scored.
    ExamPassingScoreIndicates 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.

    EventDescription
    Pre-BuildThe lab components are being deployed, as well as any cloud resources.
    Post-BuildThe lab environment has been built, but components like virtual machines may still be starting.
    First DisplayableAll components of the lab are now running and the user can now interact with the lab.
    SavingThe lab is in the process of being saved.
    SavedThe lab is in a saved state and no longer active.
    ResumingThe lab is resuming from a saved state.
    ResumedThe lab has been resumed from a saved state and the user can interact with the lab again.
    ScoringThe 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.
    ScoredThe 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 DownThe lab environment is being torn down.
    Torn DownThe lab environment is fully torn down.
    Transfer to UserThe 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 ResumeA lab has been resumed via a deferred launch page, as opposed to a direct Launch API.
    Lab Assignment CreatedA lab profile has been assigned to a user.
    Lab Profile ChangedA 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.
    ESC

    Eddy, a super-smart generative AI, opening up ways to have tailored queries and responses