Configuring Skillable Lab Webhooks

Using Webhooks is an efficient way to receive real-time information from Skillable Studio when events occur, such as changes in Lab instance status, lab assignments, or Lab Profiles.

This article helps you set up and use webhooks in Skillable Studio.

Best Practices

Webhooks, like APIs, provide an easy way to push data from one system to another when events occur. Follow these best practices to ensure reliable webhook delivery:

Configure each webhook for the specific event that matters most to your integration.
Ensure the receiving URL is publicly reachable and returns a successful HTTP status code when tested.
Review your timeout, delay, and retry settings carefully, as incorrect values can cause confusion when multiple webhooks trigger at the same time.
Use secure authentication (e.g., an authorization header or webhook secret) to validate requests.

Firewall and IP Allowlist Requirements

If your application uses a firewall or IP-based access controls, you may need to allow Skillable’s webhook IP addresses to ensure delivery succeeds.

Skillable sends webhook requests from a defined set of IP addresses. Allowlist the addresses below to avoid connection failures:

13.66.32.249
13.66.35.170
13.66.38.99
13.66.38.236
20.118.69.23
20.118.99.142
20.124.44.122
20.225.0.69
20.225.0.96
20.225.0.107
20.225.0.189
20.225.1.0
20.225.1.6
20.225.1.10
20.225.1.20
20.225.1.28
20.225.1.30
20.225.1.33
20.225.1.38
20.225.1.40
20.225.5.107
20.225.5.179
20.225.16.0
20.225.16.6
20.225.16.10
20.225.1.38
20.225.1.40
52.171.63.58
70.37.55.197
70.37.50.96

Note
IP addresses are subject to change over time. Review our documentation periodically and update your firewall rules accordingly.

Add a Skillable Studio Webhook

Webhooks are configured per API Consumer in Skillable Studio. You can create one or more webhooks for each API Consumer directly from the API Consumer detail page: ap

From Skillable Studio, navigate to Admin > Integration and then select API Consumers.
Search for the API Consumer you want to configure webhooks for.
Select the API Consumer name (or click Details) to open the detail page.
Scroll to the Webhooks section and click +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.
In the Add Webhook details, set up your Studio webhook.
Click OK to save the webhook.

Set Up Your Studio Webhook

After selecting +Add Webhook, you’ll see a set of configuration fields:

Field	Description
Name	Enter a descriptive name for the webhook.
Event	Select the event that triggers the webhook. See the Skillable Studio Webhook Events section for available events.
Verb	Choose the HTTP method the webhook uses: • GET: Retrieve data • POST: Send data • DELETE: Remove data • PUT: Update data
URL	Enter the webhook endpoint where Skillable will send requests when the configured event occurs. Note: You can include any lab replacement in the URL by enclosing it in curly braces (`{}`). For example, the lab instance ID is injected into URL using the `{id}` token. 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.
Saved Preinstance Assigned To User	When a saved preinstanced lab is assigned to a user.
Running Preinstance Assigned To User	When a running preinstanced lab is assigned to a user.

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.