Webhooks

Webhooks in WISEflow will let you know when a certain action has been performed. It works by subscribing to an event that will watch when a certain action happens in WISEflow and then send a notification. Subscribing to an event will provide notifications in almost real-time, meaning that it is easy to keep data synchronised between two systems and monitor different aspects of the flow.

When an event is detected, the webhook will trigger and call an external endpoint. An event can only be detected if it occurs within the scope of the WISEflow licence. The payload in the call will include sufficient information about the event to process it externally (or look up additional information through the WISEflow API). Every webhook is signed to allow for integrity validation.

Subscribing to a Webhook

Before you can subscribe to a webhook, you must contact Customer Support by creating a ticket in Zendesk.  Customer support will create a service task to set up the webhook and share a secret key that can be used for verification.

Setting up a webhook requires a POST callback URL.

Webhook Features

The webhook is built to ensure stability, security, and transparency with the following features:

At-least-once Delivery

  • The same message might be delivered more than once in instances with sporadic errors etc.
  • The sequence number will be unique per event (e.g., per paper submitted). But not per webhook call
  • All new webhook calls will have a unique ID

Security

  • Authorisation
  • Data retention mechanisms: Calls will be deleted after 90 days
  • Requires external endpoints to be HTTPS
  • Timestamp for calling to allow checking old messages and prevent replay attack
  • Unique ID to prevent replay attack
  • Payload is base64 encoded with an HMAC256 signature

Performance

  • Enabling a webhook can take up to 10 seconds
  • Limited to save 1 KB of the response body
  • The HTTP call to the client endpoint will time out after 10 seconds

Automatic retry of failed webhooks

  • The webhook will call the external endpoint eight times with 15 minutes intervals
Best Practice

Verification

Once the webhook is set up, you will receive a secret key used to verify future webhook calls from WISEflow. This is to ensure that the webhook payload originates from WISEflow and that the content has not been altered in any way. It is recommended that you verify the webhook signature upon receiving the payload.

The payload is base64 encoded with an HMAC256 signature using the same secret key. To verify the payload, you must re-encode the message with the shared secret key and compare the base64 signature of the original payload.
Some examples can be found here: https://github.com/danharper/hmac-examples

Grouping of Calls

Using the Trace ID, it is possible to group identical calls. This is to ensure consistency throughout the queued webhook calls. The call time can be used to only look at the newest call, thus reducing redundancy.

Answer with an HTTP Status Code as Fast as Possible

To receive a minimum number of calls, it is important that your API answers with an HTTP status code 20X as soon as the call has been received. This is to prevent the webhook from retrying the call.

Minimal Information in the Payload

The webhook payload includes a minimal amount of information, but can still be used to identify a user, a submission, or a flow. This information can be used as parameters in the API to receive more information.

Available Webhooks

Paper Submitted

Will trigger when a paper has been submitted by a participant and if the participant withdraws the paper.

Depending on how the flow is set up, different actions will trigger the event:

  • When a participant hands in a paper, an event will be triggered
  • When a participant withdraws a paper, an event will be triggered
  • When a participant hands in a group paper, one event will be triggered per group
  • When all participants in a group hand in individual papers, one event will be triggered per group member

The event can be used to trigger additional actions, such as exporting submissions.

Payload:

{
  "submissionId": 123,
  "flowId": 123,
  "userId": 123,
  "participantId": 123,
  "isHandedIn": true
}
Mark Published

Will trigger when a mark has been published by an assessor and if the mark is revoked.

Depending on the marking process, different roles will trigger the event:

  • In a double-blind marking process, the assessor will trigger the event
  • In an approval by reviewer marking process, the reviewer will trigger the event
  • In a section and/or rubric-based assessment process, the manager will trigger the event
  • When a manager gives an administrative grade
  • An event will also be triggered when the manager revokes a mark

The event can be used to trigger additional actions, such as exporting submissions and assessments.

Payload:

{
  "submissionId": 123,
  "flowId": 123,
  "userId": 123,
  "participantId": 123
}
Alternative Grade Published

The Alternative Grade webhook will be available on the WISEflow Production environment with the June 2024 release.

Will trigger when an alternative grade is added by an assessor or manager, as well as when a manager changes or removes an existing alternative grade.

The event can be used to trigger additional actions, such as exporting submissions and assessments.

Payload:

{
  "flowId": 123,
  "participantId": 123,
  "action": "updated",
  "updatedBy": 123,
  "asRole": "manager"
}

 

Grade Justification

Will trigger when a participant requests a grade justification and when an assessor submits a grade justification response [Use case]

Payload:
{
  "flowId": 123,
  "explanationRequestId": 123,
  "participantId": 123,
"assessorId": 123 }
Assignment Added

Will trigger when an assignment is created, updated, added, or removed from a flow

Payload:

{
  "assignmentId": 123,
  "assignmentReference": "example",
  "flowId": 123
}
Flow State Updated

Will trigger when the flow state is changing. E.g.: when the flow is activated or moves to the marking phase.

Payload:

{
  "state": 1,
  "flowId": 123
}
External Source Synchronisation

Will trigger when a manager requests a synchronisation on a flow set up with a Flow External Source 

Payload:

{
  "flowId": 123,
  "externalSources": [
"123",
"ABC"
]
}

Technical Information

Header and Body

The webhook header and body hold information on the current webhook call. The header and body are the same for all available webhooks.

Header

In the header you will find:

X-WISEflow-Signature-256
X-WISEflow-EventType

X-WISEflow-Event-Version
X-WISEflow-Trace-ID

X-WISEflow-CallTime
X-WISEflow-Delivery

X-WISEflow-Hook-Id
User-Agent, WISEflow


Header Description
Signature A base64 encoded HMAC256 signature of the payload. The HMAC256 signature is generated using a licence-specific secret.
Event-Type The name of the webhook e.g. paper.submission or final.mark
Event-Version The current version of the webhook
Trace-Id The Trace-Id can be used to find matching entries in the log
Call-Time The Call-Time when the call is made to the external API
Delivery The Delivery is when the call is delivered to the external API
Hook Id The webhook ID
User-Agent

The user-agent that makes the webhook call

Body

The body is a JSON object that describes the event that triggered the webhook.

In the body you will find:

{
  "Id": "",
  "action": "",
  "event": "",
  "licenseId": "",
  "eventVersion": "",
"eventPayload": {
},
"callTime": "",
"eventVersion": "",
"sequenceNumber": "",
}

Field Format Description
id string A unique ID generated by WISEflow to identify the event
action string Will be created, updated, or deleted depending on what has triggered the event.
event string The webhook you have subscribed to e.g., paper.submission or final.mark.
licenseId integer The ID of the licence that the event has been triggered from. This ID can be used if you have more than one WISEflow licence.
eventVersion string The same as the header above and is mainly used for debugging purposes.
eventPayload   The specific information received from the event
callTime integer The time the call is made to the external API
eventVersion string The current version of the webhook
sequenceNumber integer The number that corresponds to the action and the event of the given call
Was this article helpful?
0 out of 0 found this helpful

Articles in this section