Using Webhooks - Advanced

Webhooks in Cimar are a fantastic tool to automate actions in complicated workflows. The possibilities are endless and it can get quite complex so this guide serves to cover the basics of setting up a webhook in the Cimar UI.

For more advances webhooks or help with webhooks, please contact support@cimar.co.uk.

Webhooks in UI:

Navigate to "Administration" > "more" > "Webhooks" to open up the webhook settings:

In the webhook settings, a list of active webhooks will show as well as a "New Webhook" button on the right side of the screen to create a new one.

The Basics:

The minimum fields required for a webhook are name, event, URL, parameters and a user UUID to validate the action if it's to the Cimar API.

Name:
The name field is simply a visual cue that will appear in the overall webhook list once it's done. It is recommended to be as specific/descriptive as possible with the new webhook name.

Event:
The event field is a dropdown with multiple options to select what event triggers the webhook to run:

Most of these events are explained in the name itself so here are just a few of the most commonly used triggers:

When a report is added to a study
This event will trigger the webhook every time a report is added to the study. This will trigger on both reports added via the Cimar reporting suite and reports attached from a local file.

When the study status changes
This event will trigger the webhook every time the study status changes. This triggers both on manual changing of the study status and on automated changes by the system.

Called by routing rules
This event will trigger the webhook directly from a routing rule. When setting up a routing rule (see guide here) the actions can include calling a webhook. This is useful for complicated workflows to automate multiple actions at once.

URL
This is the URL for the webhook to send the HTTP request to with the relevant method. If using the Cimar API, the URL to use is "http://localhost:8020" followed by the relevant path.

Parameters
The parameters field is used to send data via the webhook to the given URL endpoint.
The format of the parameters is a JSON hash and depending on the endpoint there will be different parameters needed.
As an example, the above study/share endpoint would require a study uuid and a namespace id to run succesfully.

Validating UUID
This is the UUID of the user that will be used to validate the webhook. It is good practice as an admin to create a new user called "Webhook User" which will then show in audit trails when the webhook actions have happened. For help or questions with getting the UUIDs, please contact support@cimar.co.uk.

Study Filters:

The "Study filter field" and "Study filter field regexp" can be used as conditional filtering for when to run a given webhook.

• A simple example that filters on the number of attachments on a study could be given like this:

This will filter on the attachment_count and if there is more than 1 report attached to the study it will fire the webhook. (This filter only checks for 2-9 attachments so it's assuming there will never be 10 or more attachments).

This example could be useful to send notification emails for double reported studies or to move them to a designated namespace for reviewing.

• This filter ensure only studies in the correct namespace will be effected. 

This filter will look in the namespace associated with the uuid in the regex field. Remember to include the /<uuid-here>/ surrounding the value. 

It could be used to change the Study Status Tag for any study entering the namespace to "Assigned".

• This filter will fire when the study status tag is set to "Complete"

As there are no other filters it will trigger for any study in any namespace. It could be used in a learning environment to share any study that has been set to "Completed" with a namespace designated for marking.

• This example will only trigger if the custom field contains the word "London". 

The number after customfield- is the uuid of the field. Place the case sensitive targeted input inside the /^ $/ e.g., /^<input here>$/. 

This could be used to share automatically with an institution matching the filter name.

It is possible to filter on multiple fields using AND logic where all filters have to match.
This is done using a list in each field with comma separated values.
If the filter field contains ["field1", "field2"] then the filter field regexp must contain another list where the first value is checked against field1 and the second value is checked against field2.

This example combines the previous examples and gives us a filter that will only fire if the Custom field, Namespace & Study Status Tag all match allowing you to be as specific as your workflow requires.