Page Comparison

Home > Overview > Webhooks

...

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.

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.

...

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.

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 Veson IMOS Platform Reporting schema, serialized as JSON.

{
    "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:

...