Using Webhooks API

by Jason Stewart
Follow

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

Contents

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

Return to top

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

Return to top


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.

Return to top

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

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

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. 

Return to top

Powered by Zendesk