Webhooks API

Follow

Use webhooks to be notified about events that happen within the Skilljar course platform. Webhooks allow you to register a URL that we will notify via HTTP POST when an event occurs within your account. You may have multiple webhooks, and we will notify all active webhooks for all events.  It's suggested that you filter on event_type and react only to events you find relevant.

When an event occurs on the course platform, Skilljar attempts an HTTP POST to the URL endpoint of all active webhooks associated with your account.  The following HTTP headers are included in the POST request:

Content-Type: application/json
User-Agent: skilljar

Event Types

Course Enrollment

Triggered when a user enrolls in a course.  The content of the HTTP POST to the webhook's URL endpoint is a JSON object with the following structure:

{
    "event_type": "COURSE_ENROLLMENT",
    "timestamp": "2015-02-13T18:57:55.066475+00:00",
    "user": {
        "first_name": "Jane",
        "last_name": "Doe",
        "id": "3456789hijklmno",
        "email": "jane@example.com"
    },
    "course": {
        "id": "12345abcdefg",
        "published_course_id": "abcdefg12345",
        "title": "Example Course",
        "url": "http://example.skilljar.com/example-course"
    },
    "domain": {
        "id": "2345678defghij",
        "name": "example.skilljar.com"
    },
    "purchase": {
        "order_id": "ABCD1234",
        "original_price": "0.00",
        "purchase_price": "0.00",
        "currency_code": "USD",
        "payment_processor": "NONE"
    },
    "domain_access_code": "access"
}

Domain Enrollment

Triggered when a user enrolls in one of your private domains.  The content of the HTTP POST to the webhook's URL endpoint is a JSON object with the following structure:

{
    "event_type": "DOMAIN_ENROLLMENT",
    "timestamp": "2015-11-04T01:10:04.886958+00:00",
    "user": {
        "first_name": "Jane",
        "last_name": "Doe",
        "id": "cdefgh3456789",
        "email": "jane.doe@example.com"
    },
    "domain": {
        "id": "abcdef1234567",
        "name": "example.com"
    },
    "domain_marketing_message_optin": true,
    "domain_marketing_message_shown": false,
    "domain_access_code": "examplecode",
    "expires_at": "2016-11-04T01:10:04.886991+00:00",
    "access_code": {
        "code": "examplecode",
        "pool": {
            "name": "Example Pool",
            "id": "efghij5678901"
        },
        "id": "defghi4567890"
    },
    "custom_signup_fields_list": [
        {
            "slug": "company_name",
            "value": "company_name_value",
            "label": "My Company"
        },
        {
            "slug": "role",
            "value": "Executive",
            "label": "Role"
        }
    ]
}

Course Completion

Triggered when a user completes a course.  The content of the HTTP POST to the webhook's URL endpoint is a JSON object with the following structure:

{
    "event_type": "COURSE_COMPLETION",
    "timestamp": "2015-02-13T18:57:55.066475+00:00",
    "user": {
        "first_name": "Jane",
        "last_name": "Doe",
        "id": "3456789hijklmno",
        "email": "jane@example.com"
    },
    "domain": {
        "id": "2345678defghij",
        "name": "example.skilljar.com"
    },
    "course": {
        "id": "12345abcdefg",
        "published_course_id": "abcdefg12345",
        "title": "Example Course",
        "url": "http://example.skilljar.com/example-course"
    },
    "course_progress": {
        "latest_activity": "2015-02-13T18:45:34.711065+00:00",
        "completed_at": "2015-02-13T18:45:34.721955+00:00",
        "enrolled_at": "2015-02-13T18:42:27.733456+00:00",
        "total_lesson_count": 3,
        "completed_lesson_count": 3,
        "score": 97,
        "max_score": 100,
        "success_status": "PASSED",
        "credits_earned": "5",
        "credit_unit_plural": "Hours"
    }
}

Quiz Completion

Triggered when a user completes a quiz.  The content of the HTTP POST to the webhook's URL endpoint is a JSON object with the following structure:

{
    "event_type": "QUIZ_COMPLETION",
    "timestamp": "2015-03-25T23:38:47.164604+00:00",
    "lesson": {
        "id": "bcdefghi23456",
        "lesson_type": "QUIZ",
        "title": "Final Quiz",
        "quiz": {
            "id": "abcdefgh12345",
            "passing_percentage_correct": 86,
            "name": "My Quiz"
        }
    },
    "user": {
        "first_name": "Jane",
        "last_name": "Doe",
        "id": "3456789hijklmno",
        "email": "jane@example.com"
    },
    "quiz_completion": {
        "start_time": "2015-03-25T23:38:24.544784+00:00",
        "finish_time": "2015-03-25T23:38:47.164604+00:00",
        "passed": true,
        "question_count": 4,
        "correct_response_count": 4
    },
    "domain": {
        "id": "2345678defghij",
        "name": "example.skilljar.com"
    },
    "course": {
        "id": "12345abcdefg",
        "published_course_id": "abcdefg12345",
        "title": "Example Course",
        "url": "http://example.skilljar.com/example-course"
    }
}

Creating and Managing Webhooks

The Skilljar API is used to create, update and delete webhooks. The API endpoint for webhook management is https://api.skilljar.com/v1/webhooks.  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 may 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
}

You may HTTP PUT to an existing webhook to update it's status.  For example, if a webhook has been deactivated (see below for Retries and deactivation) - you may 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 2 second delay, doubling each time up to a maximum of a 1 hour delay.  We continue to retry to POST to the URL endpoint of the webhook up to 60 times (roughly 2 days).  If the URL endpoint is still returning a 5xx status after this point, we disable the webhook (set it's active flag to false) and will discontinue POSTing events.

If the POST fails due to an HTTP 4xx response, we immediately disable the webhook.

Have more questions? Submit a request

Comments

Powered by Zendesk