Webhooks

You can subscribe to webhooks directly using the new endpoints available in the API. For details, refer to the Webhooks section in the API documentation.

Previously, subscribing to webhooks required contacting Customer Support to create a service task and receive a secret key for verification. This manual step is no longer necessary when using the new endpoints.

Setting up a webhook requires a POST callback URL.

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

• Data retention mechanisms: Calls will be deleted after 90 days
• Requires external endpoints to be HTTPS
• Unique ID to prevent replay attack
• Payload is base64 encoded with an HMAC256 signature

Automatic retry of failed webhooks

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

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.

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]

{  
  "flowId": 123,  
  "explanationRequestId": 123,  
  "participantId": 123,
  "assessorId": 123 
}

Assignment Added

{  
  "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"
  ] 
}