Table of Contents |
---|
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.
...
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".
...
The payload of every event follows the same general format, with some fields being optional.
Field | Mandatory/optional | Description | Example/allowed values |
---|---|---|---|
| Mandatory | Unique string identifier for the given event type |
|
| Mandatory | Numeric ID for the marketplace/tenant where the event originated |
|
| Mandatory | Numeric ID for the primary object which the event is linked to (typically a User, Question, Question Set, Test Event, etc.) |
|
| Mandatory | Unique string identifier for the given object type | Allowed values:
|
| 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) |
|
| Optional | Allowed values:
| |
| 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) |
|
| Optional | Unique string identifier for the given user |
|
| Mandatory |
| Format
Example
|
| 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
Code Block |
---|
{ "event": "qti_export_ready", "marketplaceId": 1357554, "contextObjectId": 74379551, "contextObjectType": "QUESTION_SET", "timestamp": "2021-06-29T18:16:06Z" } |
...
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 |
---|---|---|---|
| Mandatory | Unique string identifier for the given extra info value type |
|
| 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. |
| 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.