Skip to main content

Webhooks

Through configuration, QuickCase can model advanced state-transition workflows and user interactions. These can be made richer, more automated or more bespoke through the use of webhooks.

A webhook in web development is a method of augmenting or altering the behaviour of a web page or web application with custom callbacks. These callbacks may be maintained, modified, and managed by third-party users and developers who may not necessarily be affiliated with the originating website or application.

— Wikipedia - Webhooks

In QuickCase, webhooks can be plugged-in at many points in the lifecycle of a case to implement business-specific validation, data retrieval or generation, 3rd-party integrations, notifications, ...etc.

Configuration

Webhooks can be configured via the QuickCase definition spreadsheet in 2 places:

  • Event-driven webhooks (start, pre-submit, post-submit) are defined per event in the CaseEvent tab.
  • Layout-driven webhooks (event page) are defined per page in the CaseEventToFields tab.

Webhooks are configured by entering the URL of the webhooks in the definition.

To keep QuickCase definitions environment-agnostic, placeholders can be set on the QuickCase deployment and used in the definition using the format ${placeholder}.

For example, given a placeholder webhooksBaseUrl:

${webhooksBaseUrl}/path/to/webhook

Implementation

Webhooks take the form of an HTTP POST request sent from QuickCase to the webhook URL configured in the definition file.

The request contains a JSON body with a contract that varies based on the webhook type (see next section "Webhooks types" for request contracts and samples).

A 200 response must be returned by the webhook implementation along with an optional JSON body (see next section "Webhooks types" for response contracts and samples).

If no response is received within the pre-defined timeout duration; or if an error code is received (4xx or 5xx), the webhook will be retried as per its retry configuration in the definition before eventually being failed.

When a webhook is failed, the event that initiated it is also failed and an error is returned to the caller (user interface or API). This guarantees that a case cannot be progressed without relevant webhooks having been successfully processed.

Access control

Contrary to QuickCase's Rest API which always operate in the context of an authenticated party (user or client) with limited permissions, webhooks do not enforce access control and fully trust the endpoint configured. This means that webhooks have full access to the data of the case they relate to and can read and alter the entirety of the case payload.

Types of webhooks

Depending on the nature and progress of the changes taking place on a case, different types of webhooks can be subscribed to:

  • AboutToStart: Before an event is initiated on a case
  • MidEvent: After the submission of an intermediary page as part of an event
  • AboutToSubmit: On submission of an event, before commit to the database
  • AfterSubmit: Following the successfully submission of an event