Vocareum can notify you when certain events, such as submission and grading, happen.

Setup

Only org admins can set up webhooks. In the editorg page, there is an events section where the webhook can be turned on/off and the url and secret token can be entered. The url is where the notification should be sent to. The secret token is a string that is used by Vocareum to generate a signature with each notification to verify its integrity.

Webhooks can be configured to send notifications on a per-assignment basis. After saving the org settings, there will be an option to turn 'Send Webhook' on for an assignment.

Secret Token

The request body of the notification is encoded using the secret token provided. The result is sent as part of the request body through voc_signature.

The voc_signature is generated by Base64 encoding the request body -- without the voc_signature -- and using an HMAC with SHA-256.

For example, a request body could look like this:

{
  "user_id":0,
  "course_id":0,
  "assignment_id":0,
  "part_id":0,
  "submission_number":1,
  "submission_time":1632555428,
  "sent_time":1632555431,
  "event_type":"student submission",
  "voc_signature":"fe6206ee935daabe3a93de8e1af97773e2a911bac31a7"
}

To verify the voc_signature, follow one of these code snippets:

(Note that the voc_signature and spaces in the request body should be excluded. Otherwise the results won't match.)

PHP:

hash_hmac('sha256', base64_encode('{"user_id":0,"course_id":0,"assignment_id":0,"part_id":0,"submission_number":1,"submission_time":1632555428,"sent_time":1632555431,"event_type":"student submission"}'), 'secret_token');

Python:

import base64, hmac, hashlib
hmac.new(b'secret_token', base64.b64encode('{"user_id":0,"course_id":0,"assignment_id":0,"part_id":0,"submission_number":1,"submission_time":1632555428,"sent_time":1632555431,"event_type":"student submission"}'.encode()), hashlib.sha256).hexdigest()

JS (Node):

crypto.createHmac('sha256', 'secret_token').update(Buffer.from('{"user_id":0,"course_id":0,"assignment_id":0,"part_id":0,"submission_number":1,"submission_time":1632555428,"sent_time":1632555431,"event_type":"student submission"}').toString('base64')).digest().toString('hex')

The result of running one of the above should be the voc_signature. If the results don't match, it could be because

voc_signature was not excluded in the request body
the wrong secret token was used
there were spaces in the request body
if there are any forward slashes, they should be escaped (e.g. and/or → and\/or)

Events

Student Submission

{
  "user_id":0,
  "course_id":0,
  "assignment_id":0,
  "part_id":0,
  "submission_number":1,
  "submission_time":1655259652,
  "sent_time":1655259653,
  "event_type":"student submission",
  "grading_page": "https://labs.vocareum.com/main/main.php?m=viewcode&back=ta&course=12345&id=12345&inviter=12345&stepid=12345",
  "voc_signature":"92af2df7e82b"
}

Grading

A notification is sent for manual grading only. On the submissions page, a dialog box will appear when saving the grades. 'Share Feedback' will save the grades and send the notification while 'Save And Close Only' will save the grades without sending the notification.

{
  "user_id":0,
  "grader_id":0,
  "course_id":0,
  "assignment_id":0,
  "part_id":0,
  "grades":{
    "Q1":3,
    "Q2":5
  },
  "submission_number":1,
  "submission_time":1655259652,
  "grades_published":1,
  "sent_time":1655189874,
  "event_type":"grade submission",
  "voc_signature":"a43e04a0fb3abbed260504a3eb0"
}

Assignment Setting Changed

Grades Published

A notification will be sent whenever the 'Publish Grade' option is changed. grades_published = 1 means the 'Publish Grade' option is 'On'.

{
  "course_id":0,
  "assignment_id":0,
  "grades_published":1,
  "sent_time":1655175401,
  "event_type":"publish grades",
  "voc_signature":"9abc04c796837180af927b5f2fca0d39"
}

Autograding

{
  "user_id": 0,
  "course_id": 0,
  "assignment_id": 0,
  "part_id": 0,
  "grades": {
    "score11": 2.34,
    "score2": 0
  },
  "submission_number": 1,
  "submission_time": 1726078306,
  "grades_published": 1,
  "sent_time": 1726078476,
  "event_type": "auto grade",
  "grading_page": "https://labs.vocareum.com/main/main.php?m=viewcode&back=ta&course=12345&id=12345&inviter=12345&stepid=12345",
  "voc_signature": "bd8e91a278b31691da4e75a3f320e50fc00f6475513ec96e"
}