The Webhooks APIs allows external systems to subscribe to events in Inspera Assessment. The Webhooks are based on the Event Log system, used by the Inspera Assessment client, but with a limited set of events for which webhooks is currently supported. The list of supported events is currently kept short, please give us feedback if there are any specific events you would like to see.
General
For both validation and for event notifications, the request sent is an HTTPS POST request, with a default timeout of 10s. If the endpoint does not respond with an HTTP 200 OK the request is considered failed, and retried. For validation requests we do not retry. For event notifications we retry 3 times before giving up.
All notifications have thin payloads, meaning they only include a minimum of information. For instance when subscribing to an event for grading completed, the notification does not include any grades, only information about the object for which the event applies.
The general format of the events are as follows:
{contextObjectId=35199862, event=confirm_final_grades, timestamp=2018-10-04T16:47:55Z}
The contextObjectId in this case refers to a test and is internal Inspera Assessment testID, also referred to as assessmentRunID (see swagger documentation for v1/test APIs https://ia.inspera.no/apidoc/#/) .
In order to verify that the event came from Inspera, and is a valid event, a hash of the message body is included in the header of the request. The hash is an HMAC SHA1 Hex of the body using the secret provided when setting up the subscription. The hash is provided in "X-Inspera-Signature".
/v1/subscription/events
This API lists all event types for which Webhook subscriptions are supported.
/v1/subscription + /v1/subscription/{subscriptionId}
These APIs allows the caller to list all current subscriptions, and register new ones, as well as delete existing subscriptions. When registering a subscription the provided endpoint is validated, and must respond with a HTTP 200 OK when called with a POST request. The request must respond within the default timeout.
Note that webhook events will only be sent out to users that are both registered listeners of the event, and that same user is either a contributor on the affected test, has write access to the affected content or is a User Administrator (depending on the contextObjectType).
The validation request looks something like this:
{contextObjectId=0, contextObjectTitle=d7e7a6dd-1c82-45ff-aea1-cbbbe9ce1bb0, event=verification, timestamp=2018-10-04T16:44:30Z}
There is no limited life-time for subscription to Inspera events. Once subscription to event has been made, it does not expire until user unsubscribes or deletes the subscription.
It is possible to get the list of events user is subscribed to by calling GET method for /v1/subscription endpoint. This method will return array all events user is subscribed to with additional information about each event found:
{
"subscriptions": [
{
"subscriptionId": 0, //used to send DELETE post to /v1/subscription/{subscriptionId} to unsubscribe form listening to event
"event": "string", //event name
"endpoint": "string", //API endpoint associated with this user and event (the API that will be called by Inspera when an event is triggered)
"lastModified": "2021-01-29T13:09:32.287Z" //date for last modified
}
]
}