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 under a Group.

{
   "payload_type":"single_user_test_results_group",
   "payload_status":"live",       // "live": Actual Results. "verify": Sample Results when setting up the Webhook form within your account.
   "test":{
      "test_id":103,
      "test_name":"Sample Test Name"
   },
   "group":{
      "group_id":104,
      "group_name":"Sample Group Name"
   },
   "result":{
      "user_id":"3276524",        // Each registered User has a unique ID user_id in ClassMarker.
      "first":"Mary",
      "last":"Williams",
      "email":"mary@example.com",
      "percentage":75.0,
      "points_scored":9.0,
      "points_available":12.0,
      "requires_grading":"Yes",   // Only Exams that include "Essay" style questions will require grading Learn more.
      "time_started":1436263102,  // Never changes per result.
      "time_finished":1436263702, // Can update on re-sends (EG: An Exam is re-opened by an Administrator to give a User more time).
      "duration":"00:05:40",
      "percentage_passmark":50,
      "passed":true,              // true/false  Note: If no "Passmark Score" is set for an exam, "true" will be used.
      "feedback":"Thanks for completing our Exam!", // Overall exam feedback as set by Administrators. Feedback is optional.
      "give_certificate_only_when_passed":false,    // true/false  Exams can be setup to disallow certificate downloading if a User fails the Exam.
      "certificate_url":"https://www.classmarker.com/pdf/certificate/SampleCertificate.pdf"
      "view_results_url":"https://www.classmarker.com/view/results/?required_parameters_here" // Unique URL per Test result for viewing formatted Test results back on ClassMarker (without being logged into a ClassMarker account). An Access control password is required for viewing access. Set this password on your My account page.
   },
  "questions": [ // Questions, User Responses and Category Results are only included if selected in your Webhook settings.
    {
      "question_id": 3542854,
      "question_type": "multiplechoice",
      "category_id": 1,
      "points_available": 2,     // Points can be to one decimal place.
      "question": "What is the first step for treating a skin burn?",
      "options": {
        "A": "Apply oil or butter",
        "B": "Nothing should be done",
        "C": "Soak in water for five minutes",
        "D": "Apply antibiotic ointment"
      },
      "correct_option": "C",
      "points_scored": 2,           // Points can be to one decimal place.
      "user_response": "C",         // If Question was not answered, "user_response" key will not exist.
      "result": "correct",          // Possible Values: correct / partial_correct / incorrect / requires_grading / unanswered.
      "feedback": "Great, and remember, never use oil on Skin burns!"  // Optional: Question Feedback. If no Question Feedback is set, "feedback" key will not exist
    },
    {
      "question_id": 10254859,
      "question_type": "multiplechoice",
      "category_id": 2,
      "points_available": 2,
      "question": "Select the options you should take when the fire alarm sounds:",
      "options": {
        "A": "Call you manager to see if you can leave the building",
        "B": "Exit the building immediately",
        "C": "Use the Lifts to exit faster",
        "D": "Use the stairwell to exit"
      },
      "correct_option": "B,D", // Note this multiple choice question contains 2 correct options.
      "points_scored": 1,
      "user_response": "B",
      "result": "partial_correct",
      "feedback": "That is incorrect, the correct answers are A and C"
    },
    {
      "question_id": 5485962,
      "question_type": "truefalse",
      "category_id": 3,
      "points_available": 1,
      "question": "Our Support staff work 7 day a week",
      "options": {
        "A": "True",
        "B": "False"
      },
      "correct_option": "A",
      "points_scored": 1,
      "user_response": "A",
      "result": "correct",
      "feedback": "That is correct, we provide 7 day support"
    },
    {
      "question_id": 3896152,
      "question_type": "freetext",
      "category_id": 5,
      "points_available": 1,
      "question": "Our company website is: www.______.com",
      "options": {
        "exact_match": [
          {
            "content": "example"
          },
          {
            "content": "example.com"
          },
          {
            "content": "www.example.com"
          },
          {
            "content": "http://www.example.com"
          },
          {
            "content": "https://www.example.com"
          }
        ]
      },
      "points_scored": 1,
      "user_response": "example",
      "result": "correct",
      "feedback": "Correct, always send our customers to our main website: www.example.com"
    },
    {
      "question_id": 6403973,
      "question_type": "matching",
      "category_id": 2,
      "points_available": 4,
      "question": "Match the options below:",
      "points_scored": 3,
      "options": {
        "A": {
          "clue": "Product faulty",
          "match": "Exchange or Refund",
          "correct_option": "A",
          "user_response": "A"
        },
        "B": {
          "clue": "Customer mis-used and broke product",
          "match": "No refund",
          "correct_option": "B",
          "user_response": "B"
        },
        "C": {
          "clue": "Customer broke factory seal",
          "match": "No refund",
          "correct_option": "B", // Note: The Exam administrator has set two Matches to equal the same Clue "B".
          "user_response": "B"
        },
        "D": {
          "clue": "Incorrect product size purchased",
          "match": "Exchange",
          "correct_option": "D",
          "user_response": "A"
        },
        "E": {
          "match": "Have customer removed by security"  // This is a Incorrect Match with no corresponding Clue, these can be used to help make Matching Questions more difficult.
        }
      },
      "result": "partial_correct",
      "feedback": "Please check your incorrect matches"
    },
    {
      "question_id": 444564,
      "question_type": "essay",
      "category_id": 5,
      "points_available": 1,
      "question": "Describe some advantages of having test papers graded instantly:",
      "points_scored": 0,
      "user_response": "Users can see their results instantly, grading is accurate, save time from manual grading",
      "result": "requires_grading",
      "custom_feedback": "",   // "custom_feedback" is only used for Essay Questions. Administrators can add when grading Essay Questions.
      "feedback": "Generic feedback here"
    },
    {
      "question_id": 442810,
      "question_type": "grammar",
      "category_id": 3,
      "points_available": 1,
      "question": "The car was parkked over their!",
      "answer": "The car was parked over there!",
      "points_scored": 1,
      "user_response": "The car was parked over there!",
      "result": "correct",
      "feedback": "Well done!"
    }
  ],
  "category_results": [ // Category results from Questions are only included if selected in your Webhook settings.
    {
      "category_id": 1,
      "name": "Health and Safety",
      "percentage": 66.7,      // Percentage can be to one decimal place.
      "points_available": 6,   // Points can be to one decimal place.
      "points_scored": 4       // Points can be to one decimal place.
    },
    {
      "category_id": 2,
      "name": "Exit Procedure",
      "percentage": 100,
      "points_available": 2,
      "points_scored": 2
    },
    {
      "category_id": 3,
      "name": "General Knowledge",
      "percentage": 100,
      "points_available": 2,
      "points_scored": 2
    },
    {
      "category_id": 5,
      "name": "Sales",
      "percentage": 50,
      "points_available": 2,
      "points_scored": 1
    }
  ]
}

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": "live",        // "live": Actual Results. "verify": Sample Results when setting up the Webhook form within your account.
  "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" // This is the Unique Identifier ID that is required to 'Start' a new Test (when taken via Links) EG: https://...?quiz=sample_quiz_id_123
  },
  "result": {
    "link_result_id": 8127364,     // Each result will have a Unique ID.
    "first": "John",
    "last": "Smith",
    "email": "john@example.com",
    "percentage": 75.0,
    "points_scored": 9.0,
    "points_available": 12.0,
    "requires_grading": "Yes",     // Only Exams that include "Essay" style questions will require grading Learn more.
    "time_started": 1436263522,    // Never changes per result.
    "time_finished": 1436264122,   // Can update on re-sends (EG: An Exam is re-opened by an Administrator to give a User more time).
    "duration": "00:05:20",
    "percentage_passmark": 50,
    "passed": true,               // true/false  Note: If no "Passmark Score" is set for an exam, "true" will be used.
    "feedback": "Thanks for completing our Exam!", // Overall exam feedback as set by Administrators. Feedback is optional.
    "give_certificate_only_when_passed": false,    // true/false  Exams can be setup to disallow certificate downloading if a User fails the Exam.
    "certificate_url": "https://www.classmarker.com/pdf/certificate/SampleCertificate.pdf",
    "view_results_url": "https://www.classmarker.com/view/results/?required_parameters_here",  // Unique URL per Test result for viewing formatted Test results back on ClassMarker (without being logged into a ClassMarker account). An Access control password is required for viewing access. Set this password on your My account page.
    "access_code_question": "What is your Employee ID?",                  // Access list usage is optional. Access lists.
    "access_code_used": "12345",
    "extra_info_question": "Which sales department are you assigned to?", // Optional. Non graded questions asked before Exam is started.
    "extra_info_answer": "New York Product 7 Divisiaon",
    "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",  // Optional. The tracking IDs sent your system.  Integration Options.
    "ip_address": "192.168.0.1"
  },
  "questions": [ // Questions, User Responses and Category Results are only included if selected in your Webhook settings.
    {
      "question_id": 3542854,
      "question_type": "multiplechoice",
      "category_id": 1,
      "points_available": 2,     // Points can be to one decimal place.
      "question": "What is the first step for treating a skin burn?",
      "options": {
        "A": "Apply oil or butter",
        "B": "Nothing should be done",
        "C": "Soak in water for five minutes",
        "D": "Apply antibiotic ointment"
      },
      "correct_option": "C",
      "points_scored": 2,        // Points can be to one decimal place.
      "user_response": "C",      // If Question was not answered, "user_response" key will not exist.
      "result": "correct",       // Possible Values: correct / partial_correct / incorrect / requires_grading / unanswered.
      "feedback": "Great, and remember, never use oil on Skin burns!"  // Optional: Question Feedback. If no Question Feedback is set, "feedback" key will not exist
    },
    {
      "question_id": 10254859,
      "question_type": "multiplechoice",
      "category_id": 2,
      "points_available": 2,
      "question": "Select the options you should take when the fire alarm sounds:",
      "options": {
        "A": "Call you manager to see if you can leave the building",
        "B": "Exit the building immediately",
        "C": "Use the Lifts to exit faster",
        "D": "Use the stairwell to exit"
      },
      "correct_option": "B,D", // Note this multiple choice question contains 2 correct options.
      "points_scored": 1,
      "user_response": "B",    // Only one option selected, hence 1/2 points awarded. Format for multiple selected options: A,B,C etc
      "result": "partial_correct",
      "feedback": "That is incorrect, the correct answers are A and C"
    },
    {
      "question_id": 5485962,
      "question_type": "truefalse",
      "category_id": 3,
      "points_available": 1,
      "question": "Our Support staff work 7 day a week",
      "options": {
        "A": "True",
        "B": "False"
      },
      "correct_option": "A",
      "points_scored": 1,
      "user_response": "A",
      "result": "correct",
      "feedback": "That is correct, we provide 7 day support"
    },
    {
      "question_id": 3896152,
      "question_type": "freetext",
      "category_id": 5,
      "points_available": 1,
      "question": "Our company website is: www.______.com",
      "options": {
        "exact_match": [
          {
            "content": "example"
          },
          {
            "content": "example.com"
          },
          {
            "content": "www.example.com"
          },
          {
            "content": "http://www.example.com"
          },
          {
            "content": "https://www.example.com"
          }
        ]
      },
      "points_scored": 1,
      "user_response": "example",
      "result": "correct",
      "feedback": "Correct, always send our customers to our main website: www.example.com"
    },
    {
      "question_id": 6403973,
      "question_type": "matching",
      "category_id": 2,
      "points_available": 4,
      "question": "Match the options below:",
      "points_scored": 3,
      "options": {
        "A": {
          "clue": "Product faulty",
          "match": "Exchange or Refund",
          "correct_option": "A",
          "user_response": "A"
        },
        "B": {
          "clue": "Customer mis-used and broke product",
          "match": "No refund",
          "correct_option": "B",
          "user_response": "B"
        },
        "C": {
          "clue": "Customer broke factory seal",
          "match": "No refund",
          "correct_option": "B", // Note: The Exam administrator has set two Matches to equal the same Clue "B".
          "user_response": "B"
        },
        "D": {
          "clue": "Incorrect product size purchased",
          "match": "Exchange",
          "correct_option": "D",
          "user_response": "A"
        },
        "E": {
          "match": "Have customer removed by security"  // This is a Incorrect Match with no corresponding Clue, these can be used to help make Matching Questions more difficult.
        }
      },
      "result": "partial_correct",
      "feedback": "Please check your incorrect matches"
    },
    {
      "question_id": 444564,
      "question_type": "essay",
      "category_id": 5,
      "points_available": 1,
      "question": "Describe some advantages of having test papers graded instantly:",
      "points_scored": 0,
      "user_response": "Users can see their results instantly, grading is accurate, save time from manual grading",
      "result": "requires_grading",
      "custom_feedback": "",   // "custom_feedback" is only used for Essay Questions. Administrators can add when grading Essay Questions.
      "feedback": "Generic feedback here"
    },
    {
      "question_id": 442810,
      "question_type": "grammar",
      "category_id": 3,
      "points_available": 1,
      "question": "The car was parkked over their!",
      "answer": "The car was parked over there!",
      "points_scored": 1,
      "user_response": "The car was parked over there!",
      "result": "correct",
      "feedback": "Well done!"
    }
  ],
  "category_results": [ // Category results from Questions are only included if selected in your Webhook settings.
    {
      "category_id": 1,
      "name": "Health and Safety",
      "percentage": 66.7,      // Percentage can be to one decimal place.
      "points_available": 6,   // Points can be to one decimal place.
      "points_scored": 4       // Points can be to one decimal place.
    },
    {
      "category_id": 2,
      "name": "Exit Procedure",
      "percentage": 100,
      "points_available": 2,
      "points_scored": 2
    },
    {
      "category_id": 3,
      "name": "General Knowledge",
      "percentage": 100,
      "points_available": 2,
      "points_scored": 2
    },
    {
      "category_id": 5,
      "name": "Sales",
      "percentage": 50,
      "points_available": 2,
      "points_scored": 1
    }
  ]
}

JSON Keys explained

Also see comments within JSON examples above.


payload_type:     // Verify if results where taken under ClassMarkers' "Group" or "Link" options. Learn more.
payload_status:   // live: Actual Results. verify: Sample Results sent when setting up your Webhook form within your account.


                  ## Group results: Identify unique individuals results using a combination of:

user_id:          // Each registered User has a unique ID user_id in ClassMarker
test_id:          // Each Test 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.


		  ## Link results: Identify unique individuals results using: link_result_id

link_result_id:   // Each Link results has a unique Link Result ID
view_results_url: // Unique URL per Test result for viewing formatted Test results back on ClassMarker (without being logged into a ClassMarker account). An Access control password is required for viewing access. Set this password on your My account page.


		  ## Questions: Questions work the same for both Groups and Links

question_id:      // Each Question has a unique ID in ClassMarker
question_type:    // Available Question types include:
                  // multiplechoice: Covers "Multiple choice" and "Multiple response" Questions. Graded by ClassMarker.
                  // truefalse: "True / False" Question. Graded by ClassMarker.
                  // freetext: "Free text" Questions. Users type a short answer. Graded by ClassMarker.
                  // matching: "Matching" Questions. User select a Match for each Clue. Graded by ClassMarker.
                  // essay: "Essay" Questions. User can write a long answer. Graded by account Administrator. Learn more.
                  // grammar: "Grammar" Questions. Check punctuation and Grammer. Graded by ClassMarker.

category_id:      // Each Question can be categorized. Each Category created has a unique ID.
points_available: // Total points question is worth. Points can be to one decimal place.
question:         // Question text. Can contain HTML formatting.
options:          // Contains answer options for Multiple choice/response, Free Text and Matching Questions. Can contain HTML formatting.
points_scored:    // Points given for the answer. Points can be to one decimal place.
user_response:    // Test takers' selected option OR typed answer. If no answer was given, no "user_response" key will exist.
result:           // If answer was: correct / partial_correct / incorrect / requires_grading / unanswered.
feedback:         // Feedback for this answer. If no Feedback exists for a Question, "feedback" key will exist. Can contain HTML formatting.
custom_feedback:  // "custom_feedback" is only used for Essay Questions. Administrators can add when grading Essay Questions.


                  ## Category results: Category results derived from Question points.

category_id:      // Each Question can be categorized. Each Category created has a unique ID.
name:             // Name given to Category by Administrator.
percentage:       // Percentage can be to one decimal place.
points_available: // Points can be to one decimal place.
points_scored:    // Points can be to one decimal place.

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.
Note
  • 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 previously saved results, that have not yet 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. This can be done before or after the Test has been taken.

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

View Results URL

Give access to colleagues who need to review Formatted Test Results (including Questions and Answers) without them needing a ClassMarker account..

See parameter: view_results_url

Including this URL is optional and needs to be turned on in the Webhook settings page. Each URL is unique and unguessable.

An Access control password is required for viewing access. Set this password on your My account page.

IMPORTANT: Receiving "Updated" Results

After Exams are completed, (E.G. After you receive the original Results Payload), the results may:
1. Require grading (Essay Question types only)
2. Be re-graded manually (Administrators may want to change points for an answer)
In these cases, results can then be manually resent via the Webhook (performed from the results pages after grading) to update your system with the upgraded score.

So we recommend you 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 if a "Test result" already exists in your database, then you can update the result rather than duplicate it.

-- 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 User (ID) could take the same Test (ID) under 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 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 check if this is
                    an Updated Test result or a New Test result 

HTML formatting in Exam Questions & Feedback

Questions (including Answer options) and Feedback fields can contain HTML formatting as set by Administrators on our Wysiwyg editors (EG: span, br, b, i, u, a, img). These HTML TAGs will be sent as plain HTML ready for display on the web.

Any non HTML formatting tags will be turned into html entities (so they will display the HTML tags rather than pass them). For example a Question might ask "What HTML tag is this TAG: <br>?", this will display the break TAG, not create a line break.

Important: Because a Users can type text responses in some question types, such as free text or essay questions, you must convert special characters in this text to HTML entities so HTML is displayed on the page as HTML TAGs, and not parsed.

Version control

Ensure you reference the JSON keys by name, to ensure any additional KEYs added in the future will not break your scripts.

Future upgrades may add, but not change or remove JSON Keys. No 'structure' changes are expected.

ClassMarker will notify customers by email with 30 days notice if new versions require any changes, but this is not expected.

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 (Third party website)

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

Troubleshoot: Check your System (Third party website)

If you are having any issues receiving results, you can check your system responses with http://onlinecurl.com/

This may highlight for example, a SSL certificate issue, or another cause your system is not functionality correctly.

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, or use separate settings such as different time limits.

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.