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.3Content-Type: application/jsonX-Hook-Signature: a5b66983f1f046ddc8b877295fb1896e07601d4ea6bd8882540cc130e8242a40Content-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