Real Time Quiz Results with WebHooks

Real Time Quiz Results with WebHooks

ClassMarker has two integration options for automatically receiving Test results back to your systems/website, Webhooks or API.

You can select which option best suits your requirements, or even use both if you need:

Webhooks Documentation

Webhooks can send your Test results to your website in JSON format.

Webhooks can be created (and verified by sending Sample Test results to your Endpoint URL) via your My account / Webhooks section of ClassMarker when logged in.

Webhook Payloads Examples

Groups: Single Test Result Payload Example


Example JSON format for a Single Test result taken by a user registered to a Group.

{
   "payload_type":"single_user_test_results_group",
   "payload_status":"verify",
   "test":{
      "test_id":103,
      "test_name":"Sample Test Name"
   },
   "group":{
      "group_id":104,
      "group_name":"Sample Group Name"
   },
   "result":{
      "user_id":"3276524",
      "first":"Mary",
      "last":"Williams",
      "email":"mary@example.com",
      "percentage":85.0,
      "points_scored":8.5,
      "points_available":10.0,
      "requires_grading":"No",
      "time_started":1436263102,
      "time_finished":1436263702,
      "duration":"00:05:40",
      "percentage_passmark":70,
      "passed":true,
      "feedback":"Thanks for completing our Exam!",
      "give_certificate_only_when_passed":false,
      "certificate_url":"http:\/\/www.classmarker.com\/pdf\/certificate\/SampleCertificate.pdf"
   }
}

Links: Single Test Result Payload Example


Example JSON format for a Single Test result taken via a Link.

{
  "payload_type": "single_user_test_results_link",
  "payload_status": "verify",
  "test": {
    "test_id": 100,
    "test_name": "Sample Test Name"
  },
  "link": {
    "link_id": 101,
    "link_name": "Sample Link Name",
    "link_url_id": "sample_quiz_id_123"
  },
  "result": {
    "link_result_id": 8127364,
    "first": "John",
    "last": "Smith",
    "email": "john@example.com",
    "percentage": 80,
    "points_scored": 8,
    "points_available": 10,
    "requires_grading": "No",
    "time_started": 1436263522,
    "time_finished": 1436264122,
    "duration": "00:05:20",
    "percentage_passmark": 70,
    "passed": true,
    "feedback": "Thanks for completing our Exam!",
    "give_certificate_only_when_passed": false,
    "certificate_url": "https://www.classmarker.com/pdf/certificate/SampleCertificate.pdf",
    "access_code_question": "What is your Employee ID?",
    "access_code_used": "12345",
    "extra_info_question": "Extra Information Question here",
    "extra_info_answer": "Extra Information Answer here",
    "extra_info2_question": "Extra Information Question 2 here",
    "extra_info2_answer": "Extra Information Answer 2 here",
    "extra_info3_question": "Extra Information Question 3 here",
    "extra_info3_answer": "Extra Information Answer 3 here",
    "extra_info4_question": "Extra Information Question 4 here",
    "extra_info4_answer": "Extra Information Answer 4 here",
    "extra_info5_question": "Extra Information Question 5 here",
    "extra_info5_answer": "Extra Information Answer 5 here",
    "cm_user_id": "123456",
    "ip_address": "192.168.0.1"
  }
}

Retrieve Quiz Results via Webhooks

Code Example

Here is an guide PHP script you can use to receive Webhook Payloads.

  1. Add the code below to a public accessible URL on your server (which you should keep a secret)
  2. Create a Webhook in ClassMarker via your My Account / Webhooks page
  3. Add your public accessible URL to the Endpoint box
  4. Check the 'Save and Verify' checkbox
  5. Select the Save button
  6. You will then see the header response your Web servers sent back such as 200 (or 404 if your Endpoint URL is incorrect)
  7. With a 2XX response, your Webhook will then be Active and can now be selected when assigning Tests to be taken.
Notes:
  • Port 80 and Port 443 only are supported
  • HTTP signature header sent as: X-Classmarker-Hmac-Sha256
<?php

// Notify ClassMarker you have received the Webhook.
http_response_code(200);

// You are given a unique secret code when creating a Webhook.
define('CLASSMARKER_WEBHOOK_SECRET', 'classmarker_secret_phrase');

// Verification function.
function verify_classmarker_webhook($json_data, $header_hmac_signature)
{

	$calculated_signature = base64_encode(hash_hmac('sha256', $json_data, CLASSMARKER_WEBHOOK_SECRET, true));
	return ($header_hmac_signature == $calculated_signature);

}


// ClassMarker sent signature to check against.
$header_hmac_signature = $_SERVER['HTTP_X_CLASSMARKER_HMAC_SHA256'];

// ClassMarker JSON payload (The Test Results).
$json_string_payload = file_get_contents('php://input');

// Call verification function.
$verified = verify_classmarker_webhook($json_string_payload, $header_hmac_signature);

// Add JSON payload to array for referencing elements.
$array_payload = json_decode($json_string_payload, true);

if ($verified)
{

	// Save results in your database.
	// Important: Do not use a script that will take a long time to respond.

}


// DEBUGGING: Log results directly to a text file to check we are receiving them.
define('DEBUGGING', TRUE);

if (DEBUGGING)
{
    // Open file in same directory to write test results JSON to.
    $file = fopen("log.txt", "w");

    // Note: Each webhook request will overwrite the last logged entry.
    fwrite($file, date("D jS M Y g:ia", time() ) . "\n\n" . $json_string_payload);

    // Close file handler.
    fclose($file);

}

?>

Database Scheme

Because our API and Webhooks both handle the same data, you can use the same database table schema design to store your results.

Even if designing your own tables, the table schema included in the Example code zip will give you a reference of table column types.

Go to our API Documentation and download the Example code zip file for more details.

Sending Sample Results

You do not need Results saved to test out your Webhook script.

You can send sample Test results directly from ClassMarker when you Create or Edit your Webhook in ClassMarker.

Sending Results in Real Time

When you have a Webhook assigned to a Test, when the Test in completed, the results will be sent in Real Time to your Webhook Endpoint Url.

Send Existing Saved Results Manually

If you have saved results that have not been sent to your Webhook, you can send those results via your Webhook manually from individual Test results pages.

Note: A Webhook must be assigned to your Test to manually send results with.

Alternatively see our API Documentation to request multiple results at once.

IMPORTANT: Receiving Updated Results

Because Exams in ClassMarker can have questions re-graded manually after the the Exam is completed, (E.G. After you receive the original Results Payload), results will then need to be manually resent via the Webhook (performed from results pages after grading) to update your system with the upgraded score.

You must build your script that receives Webhooks to first check if the result already exists and update it rather then insert it again.

Use these fields below to see is a Test result already exists and update the results rather then re-insert them.

Unique Group Results Fields
Note: The same Test can be assigned to multiple Groups, so you need to check the Group ID along with Test ID, E.G. The same Test (ID) can be taken in multiple Groups.


                // These 4 values together will be unique per test, per user

user_id:        // Each registered User has a unique ID user_id in ClassMarker
test_id:        // Each Test User has a unique ID in ClassMarker
group_id:       // Each Group has a unique ID in ClassMarker
time_started:   // Because Registered users can Retake their Tests (if allowed) use the time_started Timestamp
		   to understand if this is an Updated Test result (Regraded) or a New Test result.
		   E.G: time_started Timestamps are never updated, so if you receive the same timestamp twice
			for the same Users Test, then these results must have been resent manually.

Unique Link Results Fields
Each Link results has a unique Link Result ID.


                 // Each Link results has a unique Link Result ID

link_result_id:  // Simply use the link_result_id to understand if this is
                    an Updated Test result or a New Test result 

Failed Payload Retry Rules

We understand getting results back to your system in real time can be critical, that's why ClassMarker will retry a failed Webhook within minutes of it first failing. This is in case your system has a brief issue at the exact time of the payload delivery, results will still be delivered soon after.

Failed Webhook Scenario

  1. When a Quiz is finished, the First Webhook attempt is triggered.
  2. If the Webhook fails (a 2XX response is not received), it is tried a second time within minutes.
  3. If the Webhook fails the second time, ClassMarker will then retry once per hour for 72 hours.
  4. If your website fails to successfully respond to Webhooks 1000 times in a row (this includes retry attempts), the Webhook will be set to inactive and will no longer attempt to deliver new results or retry undelivered results until you Activate the Webhook again.

Note: When a Webhook is inactive, Test results are not sent and are not enabled for a retry, you will need to send those Test results using your Webhook manually from the results pages instead.

Note: If your Webhook has, for example, 7 failed requests in a row, then it sends a successful 2XX response, the failed requests count will reset from 7 back to 0.

Email alerts
ClassMarker will send you an email alert the first time a Webhook fails, then periodically until either your Webhooks start responding again, or your Webhook becomes inactive, in which case you will be notified it has become inactive.

How to Verifiy Webhook Payloads

When a Webhook Payload is delivered to your system, you can verify it came from ClassMarker by using the Secret Phrase you will receive when creating your Webhook. Only you and ClassMarker will know your unique Secret Phrase.

ClassMarker creates a signature (base64 hash using HMAC SHA256) using the JSON payload and your Secret Phrase, and sends the signature in the HTTP header: X-Classmarker-Hmac-Sha256 for you to use to verify on your end.

To verify the Payload came from ClassMarker, encrypt your JSON payload with ClassMarkers Webhook secret.

<?php

define('CLASSMARKER_WEBHOOK_SECRET', 'classmarker_secret_phrase');

$calculated_signature = base64_encode(hash_hmac('sha256', $json_data, CLASSMARKER_WEBHOOK_SECRET, true));

$header_hmac_signature = $_SERVER['HTTP_X_CLASSMARKER_HMAC_SHA256'];

return ($header_hmac_signature == $calculated_signature);

?>

View: Full sample code above

For other code examples in your required language, search "Examples of creating base64 hashes using HMAC SHA256 in different languages"

Request Bin for debugging

You can also use services such as http://requestb.in/ to view Test results sent via your Webhook. Request bin which will give you a unique URL to use as your temporary Endpoint URL.

After you add the request bin URL to your Endpoint URL (when creating or editing your Webhook), and you can view the 'Sample Test results' ClassMarker sends when saving and verifying your Webhook.

  1. Go to Request bin to get your unique URL
  2. Add the request bin URL to your Endpoint URL (when creating or editing your Webhook).
  3. Check the 'Save and Verify' checkbox
  4. Select the Save button
  5. You can now view the 'Sample Test results' in Request Bin

How Your Server Should Respond

Your server should respond with a 200 or any 2XX HTTP RESPONSE CODE, no body response is required.

If a 2XX response is not received, the Webhook will be Retried.

To verify the Payload came from ClassMarker, encrypt your JSON payload with your unique Webhook secret.
See: How to Verifiy Webhook Payloads

<?php

http_response_code(200);

?>

View: Full sample code above

For other code examples in your required language, search "Examples of creating base64 hashes using HMAC SHA256 in different languages"

What are Groups & Links?

Groups & Links explained

ClassMarker administrators have the opportunity to assign (distribute) exams in two ways:

  1. Groups
    By registering users into groups (handy for school classrooms or work place employee groups/departments).
    Note: The same Exam can be assigned to multiple groups.
  2. Links
    By creating a unique direct link and distributing this link either via email or by adding/embedding it in a web page (no pre registration required for Test takers).
    Note: The same Exam can have multiple direct links to help keep results separated for different groups of users.

When retrieving JSON Exam results from ClassMarker via Webhooks, you can tell if it is a Group or Link result because there will be either a Group or Link element in the JSON payload. See examples above.

  1. Groups (Registered users)

    Referenced as: Groups

    Each Group can have multiple Exams assigned to them. Group members log into ClassMarker.com to take Exams assigned to their Group.
    Registered users can also be registered in multiple Groups, which allows them to change between Groups when they are logged in and take any Exams available to their Groups.

  2. Links (Non registered Users)

    Referenced as: Links

    Each Link can only contain one Exam and has a unique link (quiz_id parameter) to access the Exam. (Public and private access options are available when administering Exams via Direct link).

Pass Data to ClassMarker (Pre Test)

When testing with our Links option, you can pass your Test takers data such as their Name, Email or their user_id from your system.

This data is saved in ClassMarker and returned with respective Webhook payloads.

This makes passing Test takers tracking details to ClassMarker easy to reference exam results back in your system.

More about Integrating your online testing

Third Party Integrations

You can also use ClassMarker Webhooks to send Exam results directly to third party services.

https://zapier.com is a service that can receive Webhooks from ClassMarker, and send Test results to a third party service of your choice.

For example: You can have a Test takers "Name, Email address and Test score" added to a Google Spreadsheet the moment an exam is finished, or have your customers Test scores updated in your CRM system or Online Recruiting Portal.

  1. In your Zappier account, create a zap of your choice using "Webhooks by Zappier" option and the third party service you which to integrate Test scores with.
  2. Copy your "unique Webhook URL" from Zappier for use in the next step
  3. Back in ClassMarker, create a Webhook and use the Zappier "unique Webhook URL" from the step above and the Endpoint URL

Once you have set up your "ZAP" on Zappier and "Webhook" on ClassMarker, you can then assign your Webhook to a Group or Link via their settings and your integration will start working.

View the many services you can integrate your Exam results into with: Webhooks with Zappier.