Page Comparison

...

Overview

Webhooks in the Veson IMOS Platform are a tool for generating real-time feedback and providing suggested changes to users as they work in the Voyage Estimator. Like Tasks & Alerts, messages are generated and displayed in the notifications panel based on logical rules applied to the current data. Unlike standard Tasks & Alerts, webhooks allow you to write whatever logic you choose in a programming language of your choice, as long as you can host it as a web endpoint. The response payload may also include suggested changes that can be automatically applied to the estimate itself.

Table of Contents

minLevel	1
maxLevel	2

Setting up a webhook in the Tasks & Alerts form

To set up a webhook, go to the Tasks & Alerts Rule Set List in the Data Center module and create a new Rule Set that applies to the Voyage or Voyage Estimate. In the Edit Rules form, select the Use Webhook checkbox.

...

Info
If you only want to run a webhook conditionally, you can use the “stop processing if true” feature of Tasks & Alerts. Create a non-webhook rule that has the condition before the webhook rule in the same rule set.

Running your webhook

To run your webhook, navigate to Estimates in the Chartering module and open an estimate in details view. Then, expand the Notifications panel. In this panel, you will see the response message that is returned by the webhook.

...

You can also access notifications in the Worksheet Estimate Column by selecting the double arrow icon >> to expand the Notifications panel for that Estimate, including Tasks, Alerts, and Webhooks.

Card details

The Webhook Card in the Notifications panel has a standard structure to it:

...

This form will show the technical details of what was sent to the webhook endpoint in the Requestand what was returned from the webhook endpoint in the Response.

Specification

Whenever a user makes a change in Estimator, the current state of the estimate will be serialized to JSON and POSTed to each configured webhook endpoint. The configured endpoints must use HTTPS and provide a certificate trusted by a common root CA. The response payload must be returned in less than 10 seconds, and the content length must be less than 1MB.

Authentication

If an API key is specified in the webhook configuration, a Veson-Webhook-Signature header is included with each HTTP POST request. The value of the header is the HMACSHA256 signature of the request body (as UTF8 Bytes) with the API key string (as UTF8 bytes) as the key.

Expand

title	Example signature verification code

Code Block

using System.Security.Cryptography;
using System.Text;

/// Utility functions
private static bool ValidateSignature(string requestContent, string signature)
{
    const string VESON_API_KEY = "hYFYXEZA36?15KMA]8hrx0FZtEfgXK1:";
    var contentBytes = Encoding.UTF8.GetBytes(requestContent);
    var apiKeyBytes = Encoding.UTF8.GetBytes(VESON_API_KEY);
    var signatureBytes = new HMACSHA256(apiKeyBytes).ComputeHash(contentBytes);

    return BytesToHex(signatureBytes) == signature;
}

private static string BytesToHex(byte[] key)
{
    StringBuilder sb = new StringBuilder();
    for (int i = 0; i < key.Length; ++i)
    {
        sb.Append(String.Format("{0:X2}", key[i]));
    }
    return sb.ToString();
}

/// Validation code
if (!ValidateSignature(requestBodyString, Headers["Veson-Webhook-Signature"])
{
// return 401 or other error code
}

Request Format

The request includes the fields configured in the webhook setup, as per the VIP Veson IMOS Platform Reporting schema, serialized as JSON.

Expand

title	Example request body

Code Block

{
    "estimateCargoes": [{
          "cargoShortName": "MINERALS"
    }],
    "vessel": {
        "dWT": 28521.95
    },
    "estimateItineraries": [{
        "seq": 100,
        "portExpensesBase": 0,
        "etaGmt": "2011-01-01T00:00:00",
        "port": {
            "name": "A.R.A.",
            "unCode": ""
        }
    }]
}

Response Format

The expected response is a JSON blob consisting of an array of alert objects. An alert object can have the following fields:

Field	Type	Description
`message`	string	The message that appears to the user. (Required)
`alertType`	One of: `Unspecified`, `PermanentWarning`, `Error`	Determines the icon that appears with the alert. (Optional)
`guid`	string (GUID)	An identifier for the alert. If provided, should be unique in the context of a single response. Can be used to indicate that a given alert is the “same” as one provided in a previous response. (Optional)
`mutation`	object	A mutation that can be applied by the user, in the same format used in the imos/applyUpdateEstimate GraphQL API (Optional)
`displayFields`	object	Customized field labels and values that can be displayed in the body of the card (Optional)
`label`	string	Field label displayed in the body of the card’s Display Fields section (Optional)
`value`	string	Matching value displayed with the label in the body of the card’s Display Fields section (Optional)
`Link`	string	A link specified by the user, presumably leading to the source of the webhook data. (Optional)

Expand

title	Example response body

Code Block

[
  {
	"message": "Charterer for Cargo GRAIN flagged for Sanctions Activity and Low Rating. Update or reach out to the Compliance Team for Approval.",
	"alertType": "PermanentWarning",
	"mutation": {
		"estimateItineraries": {
			"speed": 13.4,
			"voyageEstimateBunkers": [
				{
					"fuelType": "LSF",
					"departureQty": 175
				},
				{
					"fuelType": "LSG",
					"departureQty": 52.85
				}
				]
		}
	},
	"displayFields": [
		{
			"label": "Client Rating",
			"value":"C"
		},
		{
			"label": "Sanctions Activity",
			"value":"True - Subsidiary"
		},
		{
			"label": "Last Reviewed",
			"value":"1st September 2022"
		}
	],
    "link": "https://www.google.com/maps"
  }
]

Expand

title	Mutation Schema

This is the schema as of October 2022. The most updated schema can always be found at: https://emea.veslink.com/schema/messages/UpdateEstimate

Code Block

{
   "$id":"messages/#UpdateEstimate",
   "$schema":"http://json-schema.org/draft-07/schema",
   "additionalProperties":false,
   "properties":{
      "$schema":{
         "type":"string"
      },
      "to":{
         "type":"array",
         "minItems":1,
         "description":"The target company code(s) to send the message to",
         "items":{
            "type":"string",
            "description":"A target company code to send the message to"
         }
      },
      "comment":{
         "type":"string",
         "description":"Additional comment to attach to the message being sent"
      },
      "intent":{
         "type":"string",
         "const":"UpdateEstimate",
         "description":""
      },
      "data":{
         "type":"object",
         "additionalProperties":false,
         "properties":{
            "estimateID":{
               "type":"string"
            },
            "vesselCode":{
               "type":"string"
            },
            "voyageCommenceDateLocal":{
               "type":"string",
               "format":"date-time"
            },
            "estimateCargoes":{
               "type":"array",
               "items":{
                  "type":"object",
                  "additionalProperties":false,
                  "properties":{
                     "cargoSeq":{
                        "type":"number"
                     },
                     "cargoID":{
                        "type":"number"
                     },
                     "cargoShortName":{
                        "type":"string"
                     },
                     "chartererShortName":{
                        "type":"string"
                     },
                     "cpQty":{
                        "type":"number"
                     },
                     "cargoUnit":{
                        "type":"string"
                     },
                     "freightRateBase":{
                        "type":"number"
                     },
                     "curr":{
                        "type":"string"
                     },
                     "freightType":{
                        "type":"string"
                     },
                     "laycanFromLocal":{
                        "type":"string",
                        "format":"date-time"
                     },
                     "laycanToLocal":{
                        "type":"string",
                        "format":"date-time"
                     },
                     "optionPercentage":{
                        "type":"number"
                     },
                     "option":{
                        "type":"string"
                     }
                  }
               }
            },
            "estimateItineraries":{
               "type":"array",
               "items":{
                  "type":"object",
                  "additionalProperties":false,
                  "properties":{
                     "seq":{
                        "type":"number"
                     },
                     "portNo":{
                        "type":"number"
                     },
                     "cargoSeq":{
                        "type":"number"
                     },
                     "portFunction":{
                        "type":"string"
                     },
                     "loadDischargeQuantity":{
                        "type":"number"
                     },
                     "loadDischargeRate":{
                        "type":"number"
                     },
                     "rateUnit":{
                        "type":"string"
                     },
                     "portExpensesBase":{
                        "type":"number"
                     },
                     "weatherFactorPercentage":{
                        "type":"number"
                     },
                     "terms":{
                        "type":"string"
                     },
                     "idleDays":{
                        "type":"number"
                     },
                     "extraPortDays":{
                        "type":"number"
                     },
                     "extraSeaDays":{
                        "type":"number"
                     },
                     "speed":{
                        "type":"number"
                     },
                     "portDays":{
                        "type":"number"
                     },
                     "demurrageDays":{
                        "type":"number"
                     }
                  }
               }
            },
            "categoryID":{
               "type":"number"
            },
            "contractType":{
               "type":"string"
            },
            "commencePort":{
               "type":"object",
               "additionalProperties":false,
               "properties":{
                  "portNo":{
                     "type":"number"
                  },
                  "name":{
                     "type":"string"
                  }
               }
            },
            "weatherFactorPercentage":{
               "type":"number"
            },
            "dailyCost":{
               "type":"number"
            },
            "addressCommission":{
               "type":"number"
            },
            "speedBallast":{
               "type":"number"
            },
            "speedLaden":{
               "type":"number"
            },
            "terminatingPort":{
               "type":"string"
            },
            "lockProfit":{
               "type":"boolean"
            },
            "profit":{
               "type":"number"
            },
            "lockTCE":{
               "type":"boolean"
            },
            "tcE":{
               "type":"number"
            },
            "voyageEstimateBunkers":{
               "type":"array",
               "items":{
                  "type":"object",
                  "additionalProperties":false,
                  "properties":{
                     "fuelType":{
                        "type":"string"
                     },
                     "initialPrice":{
                        "type":"number"
                     }
                  }
               }
            },
            "commit":{
               "type":"boolean"
            },
            "initFromBenchmark":{
               "type":"boolean"
            },
            "atSeaBunkerPrice":{
               "type":"number"
            },
            "inPortBunkerPrice":{
               "type":"number"
            },
            "vesselImo":{
               "type":"string"
            }
         }
      }
   }
}

Info

If you want “applied” mutations to appear as applied to the end user, include a consistent GUID (globally unique identifier) with the alert object. If no GUID or a new GUID is returned, the mutation will be interpreted as new on the front-end and displayed as such to the end users.

Regardless, reloading an estimate will reload all webhook alerts and their statuses. This is planned for future improvement.

...

Versions Compared

Old Version 17

New Version Current

Key

Overview

Setting up a webhook in the Tasks & Alerts form

Running your webhook

Card details

Specification

Authentication

Request Format

Response Format