Creating a Webhook Subscription
Create Webhook Subscription Dialog
Open the Webhooks module in the Alerts section.
Click Create Webhook Subscription
in the top right corner.Fill in the required fields (marked with *) for each step in the dialogue.
Click Create.
Types of Webhook Subscriptions
The VMS supports three types of webhook subscriptions: HTTP, Email, and Websocket.
HTTP and Email: These types send notifications as a HTTP request or as an email.
Websocket: This type pushes notifications directly to users via VMS.
Below are illustrations and detailed descriptions of the fields required to create a new Webhook Subscription for each type.
Receiver Step
Basic Authentication requires filling out a Username and Password for the endpoint. Request Token requires filling out an Access Token Request Url and an Access Token Request Body , with the other fields being optional.
No authentication configuration is required for email.
No authentication configuration is required for websocket.
Trigger Step
The Trigger specifies the condition that must be met to send a notification to the Receiver. Below are examples of various Webhook Subscription types, ranging from simple to more complex Trigger conditions.
Default example: will send notifications to the Receiver whenever a Cargo object your user has access to is updated.
Example Expression
To trigger a notification in this example, multiple conditions must be satisfied:
The
cargoQuantitymust be modified and be greater than or equal to 1000.The
chartererkey of the Cargo must match a specific user key.
These criteria ensure that notifications remain relevant and informative.
The Field can be chosen using the field selector modal, similar to selection in lists. Conditions can be customized with the Add Group option, allowing multiple combinations of AND / OR conditions. A simplified preview of the conditions is shown at the bottom of the modal. A Variable can be selected to create conditions based on the subscribed user's ID, name, or email.
When having an array in the field path, its possible to add an array filter when selecting field. For instance if you only want to include Marine Accountants from Voyage Users:
Easily set up by selecting a pre-existing alert script. Ensure the script is already created in the Alert Scripts module under Alerts, and it should include its own configurable object type and event type triggers.
All Object Types example: requires little configuration on the Trigger step, as it will create Webhooks for all Object Types for a given Event Type. This type is only allowed for a HTTP Receiver and should be thought through, as it may flood the server with notifications.
This mode creates a webhook for all object types, which may flood the server with notifications. Most use cases will be covered by Default and Expression Webhooks. If you are unsure, use one of these instead.
Payload Step
Template Message and Fields are optional. Template Message allows for a custom message where field values from the object can be inserted in the sent notification.
Fields limit what fields should be returned in the notification and can look like this {"fieldName1":"*","fieldName2":"*"}. Read more about how to specify Fields here.
General
All options are optional except User, which must be selected. This should in most cases be set to the user intended to receive the notification. As the permissions of that User decides the access to objects when the notification is sent. Failing notifications could be due to the User not having the right access.
Additional behavior modifiers can be enabled here, such as preventing unsubscription, limiting triggers to main object changes, or excluding metadata from the payload.
When the Trigger uses an Alert Script, the General step also includes scheduling. This allows you to set the start time for when the Webhook begins running and the interval between each run. The description icon (i) can be hovered over to reveal additional information about their function.
Last updated
Was this helpful?