Webhooks

1 General
2 Format
3 AutoUnsubscribe

The Webhooks APIs allow 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.

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 include thin JSON payloads on a fixed format. The payloads include base metadata, but does not include extensive data related to the event. This is done to ensure a consistent and controlled payload size. 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. Fetching more detailed information can then be done via the APIs using the identifiers referenced in the webhook payload.

Note that notifications will not be sent out to subscriptions registered on the same user that is defined as the triggering user for the event. This is consistent with how notifications are handled for other notification types in Inspera, and is done to avoid spamming a user with notifications about their own actions in the system.

Verification

In order to verify that an 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".

Webhook APIs

/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 where 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 object type affected by the event). Users with extended access received all applicable events, regardless of the explicit permissions or contributor roles on individual objects.

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 lifetime for subscription to Inspera events. Once a 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.

Format

The payload of every event follows the same general format, with some fields being optional.

Field	Mandatory/optional	Description	Example/allowed values

Field	Mandatory/optional	Description	Example/allowed values
`event`	Mandatory	Unique string identifier for the given event type	`revision_status_updated`
`marketplaceId`	Mandatory	Numeric ID for the marketplace/tenant where the event originated	`1357554`
`contextObjectId`	Mandatory	Numeric ID for the primary object which the event is linked to (typically a User, Question, Question Set, Test Event, etc.)	`74379551`
`contextObjectType`	Mandatory	Unique string identifier for the given object type	Allowed values: `ASSESSMENT_RUN` `QUESTION_SET` `QUESTION` `ITEM_BANK` `QTI_SECTION` `DOCUMENT` `MARKETPLACE` `USER` `PRESET` `ASSET` `CUSTOM_USER_ROLE`
`associatedObjectId`	Optional	Numeric ID for the secondary object linked to the event (typically either the object referenced in a value update, or a nested object within the context object - e.g. a candidate within a test event)	`74379551`
`associatedObjectType`	Optional		Allowed values: `QUESTION_SET` `CANDIDATE` `COMMITTEE` `GROUP` `GRADING_INSTRUCTIONS` `USER` `DOCUMENT` `USER_ASSESSMENT` `USER_QUESTION` `QUESTION` `MARKETPLACE_PROPERTY`
`triggeringUserId`	Optional	Numeric ID for the user that triggered the event - only included when the event was triggered via a manual user action (i.e. not system triggered events)	`74379551`
`triggeringUserName`	Optional	Unique string identifier for the given user	`abc`
`timestamp`	Mandatory	`ISO_8601_DATE_AND_TIME_WITH_SECONDS_UTC`	Format `yyyy-MM-dd'T'HH:mm:ss'Z'` Example `2021-06-29T18:16:06Z`
`extraInfo`	Optional	Any additional information provided for the given event type. Details of the values provided is defined per per event type.	See separate section on extra info below.

Example

{
  "event": "qti_export_ready",
  "marketplaceId": 1357554,
  "contextObjectId": 74379551,
  "contextObjectType": "QUESTION_SET",
  "timestamp": "2021-06-29T18:16:06Z"
}

Extra info

The extraInfo follows a general format, however the details of the values provided depend on the specific event type.

Field	Mandatory/optional	Description	Example/allowed values

Field

Mandatory/optional

Description

Example/allowed values

type

Mandatory

Unique string identifier for the given extra info value type

String

Date

customUserRole

role

xml

accessLevel

adminLevel

scoreDisplayMode

JSON

value

Mandatory

The updated value for the relevant field

Typically a single string value with either an undefined string, date or specific format (see type field above). If type is JSON the value is a JSON object with the format being dependant on the specific event type.

previousValue

Optional

The previous value for the relevant field

Typically a single string value with either an undefined string, date or specific format (see type field above). If type is JSON the value is a JSON object with the format being dependant on the specific event type.

AutoUnsubscribe

Even if there is a call to unsubcsribe to webhook-notifications that should no longer be in use, we have experienced that some subscriptions set up for testing is just abandoned when testing is done, leving the notifications active - also after the endpoint has stopped working.
Since this actually imposes a problem, we have create a feature for automatically unsubscribe ‘dead’ subscriptions.
We will ofc acknowledge that en endpoint my have temporary issues, and therefore we check several times before actually unsubscribing.
We currently issue a validation-call every 8 hours to each registered endpoint (if two subscriptions uses same endpoint, we only send one message). If an endpoint fails on 3 successive calls, all subscriptions to that endpoint will be automatically unsubscribed - Note this features is controlled by a MPP, and has to be turned on to start unsubscribing.