Skip to main content

Webhooks: AboutToSubmit

AboutToSubmit webhooks are triggered after the case creation or progression has been submitted to the API but before it has been accepted. This gives webhooks control over accepting and altering events before they are applied to the case.

Use cases​

  • Validation of new/updated case data
  • Logic initiated by diff between old and new case data (eg. notification when email address has been updated)
  • Generation of additional, computed case data (including based on values provided as part of event)
  • Override of workflow target state (eg. diverge from main workflow when error condition met)
  • Notifications with acknowledgement guaranty

Contract​

Request​

Payload:

{
    "case_details_before": {
        "id": "string",
        "case_type_id": "string",
        "created_date": "string",
        "last_modified": "string",
        "state": "string",
        "security_classification": "string",
        "case_data": {
            "case_field1": "value_before",
        },
        "data_classification": {
            "case_field1": "<Security classification>",
        }
    },
    "case_details": {
        "id": "string",
        "case_type_id": "string",
        "created_date": "string",
        "last_modified": "string",
        "state": "string",
        "security_classification": "string",
        "case_data": {
            "case_field1": "value_now",
            "case_field2": "value2",
        },
        "data_classification": {
            "case_field1": "<Security classification>",
            "case_field2": "<Security classification>",
        }
    }
}

case_details_before- Previous version of case (currently persisted), provided to facilitate comparison with the case data case_detailsin the context of current event transaction.

Response​

Status: 200

Payload (optional):

{
    "data": {
        "case_field1": "",
        "case_field2": "",
        "case_field3": "",
    },
    "errors": [
        "Error 1",
    ],
    "warnings": [
        "Warning 1",
    ],
    "override_state": ""
}
  • data (optional) - the altered, complete case data to be returned. Any case fields present in the request case_data and omitted from the response data will be missing from the submit event payload and would appear empty in the UI. The data returned in the response will be validated against the case type definition, including checks for valid field names and data type correctness. In case of any validation errors, the submit event call will fail and the error messages will be returned with HTTP status 422 back to initiator of the submit event (UI or API). When data is omitted from the webhook response, then the case data as provided in the request will be used instead.
  • errors (optional) - list of error messages to be returned. If there are any errors, the about to submit event call will fail and the error messages will be returned with HTTP status 422 back to initiator of the submit event (UI or API).
  • warnings(optional) - list of warning messages to be returned. If there are any warnings, the about to submit event call will fail and the warning messages will be returned with HTTP status 422 back to initiator of the submit event (UI or API) unless the about to submit URL is configured with query parameter ignore-warning=true.
  • override_state(optional) - When provided it will override the workflow target state. This allows workflow to diverge from the primary, default path when specific conditions are met; for example moving into an error state requiring asynchronous review when failure of the submission is not desired.