Webhooks are automated messages sent from programs and apps to a unique web address. Whenever an event occurs within your Skilljar course platform, you can use webhooks to receive notifications about it.
In this article, we'll walk you through how to create and manage webhooks within the Skilljar Application Programming Interface (API). You'll also find more information about the event types that use webhooks and their HTTP structure.
For more information about the Skilljar API, check out our help article: Getting Started with the Skilljar API (Skilljar dashboard access is required).
What are webhooks?
Webhooks are automated messages sent from programs and apps to a unique web address. You can use webhooks to register a web address (URL) and receive notifications whenever an event happens within your Skilljar course platform, specifically on your training domains, such as course enrollment.
We'll send you these notifications using an HTTP POST request method, using these HTTP headers:
Content-Type: application/json User-Agent: skilljar
- You can read more about HTTP POST requests in the Creating and Managing Webhooks section.
You can also use an integration platform as a service (iPaaS) Connector to listen for Skilljar webhooks and pass training data to other tools that your company uses. Read more about this at iPaas Webhook Setup Instructions.
- Note: Using webhooks doesn't count toward your API usage or throttling limits.
Creating and Managing Webhooks
You can create, update, and delete webhooks within the Skilljar API. You can manage your API endpoint for webhooks at https://api.skilljar.com/v1/webhooks.
For more information about the Skilljar API, check out our help article: Getting Started with the Skilljar API (Skilljar dashboard access is required).
- Note: The Skilljar API is intended for backend integrations only, and API keys should not be included in any user-facing code (example: Skilljar Theme).
An HTTP GET request will list the existing webhooks. For example:
GET /v1/webhooks
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": "abcd1234",
"target_url": "http://example.com/skilljar-hook-processor",
"active": true,
"deactivate_reason": null
}
]
}
HTTP POST requests are used to create a new webhook. You can POST JSON data, or form-encoded parameters to the API to create a webhook. An example JSON POST body looks like:
POST /v1/webhooks
{
"target_url": "http://example.com/your-hook-processor",
"active": true
"event_type": "COURSE_ENROLLMENT"
}
You can use HTTP PUT to update an existing webhook's status. For example, if a webhook has been deactivated (see Retries and deactivation section) - you can re-activate it, or change the target_url:
PUT /v1/webhooks/abcd1234
{
"target_url": "http://example.com/updated-processor"
}
Retries and deactivation
If the POST request from the Skilljar platform fails with an HTTP 5xx error, we retry the POST with an exponential back-off delay starting with a two-second delay, doubling each time up to a maximum of a one-hour delay. We continue to retry to POST to the URL endpoint of your webhook up to 60 times (roughly two days). If the URL endpoint still returns a 5xx status after this point, we'll disable the webhook (set its active flag to false) and discontinue POSTing events.
If the POST fails due to an HTTP 4xx response, we immediately disable the webhook.
Event Types
You can set up webhooks for just one specific event type, or you can have multiple active webhooks, with each one receiving a notification for every event that occurs.
The event types are:
- Course Enrollment
- Domain Enrollment
- Course Completion
- Lesson Completion
- Path Completion
- Path Enrollment
- Quiz Completion
- Purchase
- Dashboard Tasks Created
To set up a webhook for a single event or separate individual events, edit this code, changing the "target_url" to your registered web address and "event_type" to one of the event types listed above.
POST /v1/webhooks
{
"target_url": "http://example.com/your-hook-processor",
"active": true
"event_type": "COURSE_ENROLLMENT"
}
Enter the event type in this format:
COURSE_ENROLLMENTDOMAIN_ENROLLMENTCOURSE_COMPLETIONLESSON_COMPLETIONPATH_COMPLETIONPATH_ENROLLMENTQUIZ_COMPLETIONPURCHASE_FULFILLMENTDASHBOARD_TASK_CREATED
Repeat this step to create a webhook for another individual event type. Alternatively, if you want to set up webhooks for all event types, simply leave the "event_type" field blank.
Webhook Security (Basic authentication & Additional Headers)
When you activate a Skilljar webhook, you can add Basic Authentication fields and/or Additional Custom Headers for your webhook endpoint.
Adding Custom Headers or Basic Authentication adds an extra level of security and ensures your webhook endpoint can deny any post messages that aren’t generated from Skilljar.
Basic Authentication - you can set any username and password which will be used as Basic Authentication. If these fields are set - the specified basic_auth_username and/or basic_auth_password will be encoded and included in the Webhook Post Header
Additional Headers - You can set as many Additional Headers (key pairs) as you want, and these will be included in every POST from Skilljar to the configured webhook endpoint.
On creation, you can set both the Header and the Value strings which will be included as additional headers in every Webhook Post.
Note, these must use double quotes when specifying the key pairs in this list: "example_client_id":"abdcjkcjdidshdshkn"
An example Creation post with both of these configured can be seen below:
POST /v1/webhooks
{
"target_url": "http://example.com/your-hook-processor",
"active": true
"event_type": "COURSE_ENROLLMENT"
"basic_auth_username": "customer_username_input"
"basic_auth_password": "customer_password_input"
"additional_headers": {
"x-my-new-header": "string",
"client_id": "examplestring2",
"client_secret": "abcdefg1234567"
}
}
Testing Webhooks
You can PING a webhook to send a "test message" to confirm that a webhook is receiving the post from Skilljar. If you'd prefer data to be able to set up automation, then we recommend creating a test user on your course platform and triggering a real event.
<%= heading %>