Using Webhooks API

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 towards 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 is still returning a 5xx status after this point, we'll disable the webhook (set its active flag to false) and will 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_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. Alternatively, if you want to set up webhooks for all events types, simply leave the "event_type" field blank. 

Basic authentication

When you activate a Skilljar webhook, you have the option to add Basic Authentication username and password fields for your webhook header.
Adding Basic Authentication adds an extra level of security and makes sure your webhook endpoint can deny any post messages that aren’t generated from Skilljar. 

When activating a webhook via the Skilljar API, you can specify the username and password for the webhook header by adding the basic_auth_username and basic_auth_password fields, as 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"
}

If these (either or both of these) fields are set - the specified basic_auth_username and/or basic_auth_password will be encoded and included in the webhook Post Header.