Using Webhooks API

  • Updated

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

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:

Event Type Triggered When This Happens

Domain Enrollment

Learner creates an account on a training domain

Course Enrollment

Learner enrolls (or is enrolled) into a course

Course Completion

Course is marked complete

(by completing all required lessons or via an external event)

Lesson Completion

Lesson is marked complete

(through the learner action or via an external event)

Path Enrollment

Learner enrolls (or is enrolled) into a Path

Path Completion

Path is marked complete

(by completing all courses in the path, or via an external event)

Quiz Completion

Quiz Attempt is Completed 

(note: if the quiz has a manual graded Task associated, this event will not trigger until the task is completed)

Purchase Fulfillment

Purchase event is fulfilled/completed
Dashboard Tasks Created A Task has been created that requires a review on the dashboard

 

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_ENROLLMENT
  • DOMAIN_ENROLLMENT
  • COURSE_COMPLETION
  • LESSON_COMPLETION
  • PATH_COMPLETION
  • PATH_ENROLLMENT
  • QUIZ_COMPLETION
  • PURCHASE_FULFILLMENT
  • DASHBOARD_TASK_CREATED

Repeat this step to create a webhook for another individual event type. If you want to set up webhooks for all event types, simply leave the "event_type" field blank in your Post - all event types will be posted to your "target_url".

 

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. 

Was this article helpful?

1 out of 1 found this helpful