Webhooks Configuration

This article describes how to configure Webhooks in Coassemble

Lucas avatar
Written by Lucas
Updated over a week ago

Use Webhooks to get Coassemble to notify your system when events happen in Coassemble - for example when a student completes a course.

The available fields you can retrieve data for include:

  • Learner (user): ID, First Name, Last Name, Username, Email address

  • Course: ID, Code, Title

  • Group: ID, Name

  • Tracking Data (course completion): ID, Score, Passed, Passing grade, Total time spent, Commenced, Completed, Report URL (a link to a route with more data)

  • Initiator (Enrollment): ID, First Name, Last Name, Username, Email address


If Webhooks has been enabled on your workspace, you can enable individual hooks from the integrations page.

Follow these simple steps to configure your web hook:

Step 1: Select the Course Completed webhook

Step 2: Enter the URL of your API endpoint.

Step 3: Click the test button to make sure the webhook works. It will receive a tick if the request received a successful response. You should check that your API has functioned properly as well. - If there is an error you will see a small x and you can hover over the button to see more details.

Once you're happy, ensure that the hook is enabled.


Example of a request for 'Course completion':

POST https://yoursite.com/api/completion {

"id": 173512,
"commenced":"2017-02-08T10:30:27+11:00",
"completed":"2017-02-08T10:30:27+11:00",
"passed": true,
"progress_percent": 100,
"report_url":
"https://yourdomain.coassemble.com/rest/builder/reports/course..."
"score": {"max":100,"min":0,"raw":95,"percentage":95},
"score_percent": 95,
"student_name": "Sally Student",
"total_time": 12000,

"group": {
"id": 3415,
"name": "Sydney"
},

"course": {
"code": “HTD”,
"id": 6618,
"title": "How to train a dragon"
},

"user": {
"username": "sally_student",
"firstname": "Sally",
"lastname": "Student",
"avatar": "url.png",
"active": true,
"timezone": "Australia/Sydney",
"id": 3645888
},

}

Returns {"return_url": "https://yoursite.com/course/ABC101/home"}

Example of a request for 'Learner enrolled':

POST https://yoursite.com/api/enrolment {

"initiator": {
"username": "terrance_teacher",
"firstname": "Terrance",
"lastname": "Teacher",
"id": 11789,
"email": "terrance@coassemble.com"
},

"group": {
"id": 3415,
"name": "Sydney"
},

"course": {
"code": “HTD”,
"id": 6618,
"title": "How to train a dragon"
},

"user": {
"username": "sally_student",
"firstname": "Sally",
"lastname": "Student",
"id": 3645888,
"has_email": true,
"active": true,
"timezone": "UTC",
"email": “sallystudent@coassemble.com”
},

"date": "2017-08-09T20:32:56+0000",
"id": 18141,
"permissions": [
"study"
]
}


Completion Return URL

Optionally, your API may return a JSON object with additional info. For a Course Completed webhook, you may return a return_url that the student will be directed to when they have completed the course.

When the student has completed the course, they will see this message, which will take them to the return url, or back to the Coassemble dashboard if none is provided.


Security

You’ll want to determine that the request is genuine, and for that you can generate a secret token in the Webhooks settings, and we will sign the header of the request with the hash of the request . You can use the secret token to confirm the authenticity of the request.

User-Agent: GuzzleHttp/6.2.1 curl/7.49.1 PHP/7.0.3

Content-Type: application/json
X-Hook-Signature: a5b66983f1f046ddc8b877295fb1896e07601d4ea6bd8882540cc130e8242a40
Content-Length: 177

An example of the request headers your webhook will receive - note the X-Hook-Signature header.

To verify that the message is genuine, simply generate a SHA-256 HMAC of the request body, using the provided hook secret as the key, produce a hex digest, and compare it with the signature we provide in the X-Hook-Signature header.

Here is sample code for generating the HMAC in various languages. https://gist.github.com/thewheat/7342c76ade46e7322c3e 

Did this answer your question?