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.
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.
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
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
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
}Will trigger when a grade has been finalised on a participant and if the finalised grade 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 finalised grade
The event can be used to trigger additional actions, such as exporting submissions and assessments.
Payload:
{
"flowId": 12345,
"userId": 12345,
"submissionId": 12345,
"participantId": 12345,
"grade": 10,
"gradeDate": "2024-07-16T00:00:00Z",
"adminGrade": null,
"adminGradeDate": null
}Will trigger when an alternative grade is published 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,
"grade": null,
"gradeDdate": null,
"adminGrade": "UA",
"adminGradeDate": "2024-07-16T00:00:00Z",
"action": "created",
"updatedBy": 12345,
"asRole": "manager"
}
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
}Will trigger when an assignment is created, updated, added, or removed from a flow
Payload:
{
"assignmentId": 123,
"assignmentReference": "example",
"flowId": 123
}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
}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
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 |