Background
By means of a Webhook, assessmentQ can provide external platforms with real-time information.
assessmentQ offers the following Webhooks:
- Session finished
- Assignment results published
When you set up a subscription to (one of) these Webhooks, assessmentQ immediately delivers a message to the external platform when the expected event has occurred, for example when a new session has been finished or when new results are available for an assignment.
As an administrator, you can subscribe to the assessmentQ Webhooks via the Integrations module.
Note: Subscribing to the assessmentQ Webhooks is also supported via the assessmentQ API.
Subscribing to a Webhook
Subscribing via the assessmentQ Backoffice
Proceed as follows to subscribe to a Webhook:
- Open the Integrations module in Settings.
Result: The Webhook subscriptions overview is shown. -
Click the Add button in the top right corner.
Result: The Add Webhook subscription popup is shown.
-
Enter a name for your subscription.
Note: In case you subscribe to the Assignment results published Webhook, the name of the subscription will be shown in the Assignment reports module when you select the option Send results.
- Select the event you want to subscribe to.
- Enter the URL to which the data will be sent when the Webhook is triggered.
- Click Save.
Result: The Webhook subscription overview is updated. If you subscribed to the Session finished Webhook, a message will be sent as soon as a participant clicks the Finish button in a session. If you subscribed to the Assignment results published Webhook, a message will be sent as soon as an analyst clicks Send results for an assignment in the Assignment Reports module.
Subscribing via the assessmentQ API
Similar to subscribing via the backoffice, you can also subscribe through our API using the following API call:
POST /v2/subscriptions
In the body, you will need to provide the same data:
- A name for the webhook
- Which events you would like to subscribe to
- The URL which we need to call
- The security key to use
This last option, the security key, is not available through our assessmentQ backoffice. This key enables you to have extra protection against a Man-In-The-Middle attack. If this security key is provided, we will add a header "X-Hook-Signature" to every call of the webhook which contains a certain value. This value is calculated by hashing the payload according to the HMACSHA256 algorithm, with the provided security key as encryption key.
For example: A session finished resthook with payload
SessionId = 123
and security key "abc"will result in a "X-Hook-Signature" which contains
"17c5577856d43d0d2abbf6f6530b46f8093ce1f30be862919febdb7b49d61d7b".
Confirming the subscription
Upon subscribing to an assessmentQ webhook, we will perform a confirmation. The registration of the webhook will only be successful after this confirmation. As confirmation, we send a test-request to the given URL. This test-request is a POST request which contains an empty body and an "X-Hook-Secret" header.
To validate your resthook, the reponse should be a NoContent (HTTP 204) reponse that uses the same header and header value as the request header. This means that if the test request contains a "X-Hook-Secret"-header with value "abc123", your response should also contain a "X-Hook-Secret"-header with value "abc123".
If you receive a 422 "BadEntity" response while trying to add a resthook, the supplied URL did not return the response we expected and the test request has failed. Your webhook will not be registered.