Webhooks

Introduction

enVision Cloud supports webhooks, which allow for your system to receive notifications when measurements are captured from any supported device in your fleet. This can be an ideal integration strategy when you wish to receive notification of measurement transaction events originating from enVision devices as they occur.

To work with webhooks, create an event destination as an HTTPS webhook endpoint. Once registered with enVision Cloud, it will be called by enVision Cloud when measurement transactions are received from your connected devices. With each call, enVision Cloud submits a JSON payload containing details of the transaction.

You can register a total of three webhooks in enVision Cloud.

Getting Started

To start receiving webhook events in your app, create and register a webhook endpoint:

1. Create a webhook endpoint handler to receive POST requests.
2. Test your webhook endpoint handler with a supported enVision device or by using enVision Cloud Simulation mode.
3. Register your endpoint within the enVision Cloud portal.
4. Secure your webhook endpoint.

Creating the handler

Set up an HTTPS endpoint function that can accept webhook requests with a POST method. Ensure your function quickly returns a successful status code (2xx) prior to processing any complex logic that could result in a timeout. For example, you should return a 200 status code before updating source records in your WMS platform.

The payload passed to webhook endpoints is a JSON-formatted Transaction object.

Registering the endpoint

Register your webhook endpoint using the provided interface in the enVision Cloud Portal. Navigate to Webhooks section from the navigation bar. Add a new endpoint by clicking the "Add" icon.

You will be presented with the webhook details screen.

Specify a Name for your webhook, as well as the endpoint handler.

You can specify filters to control when the endpoint is fired. The options are:

• Fire on Locally Triggered Measurements. Toggle this switch on to configure the webhook to be called whenever a measurement transaction is created due to a device-local trigger. This may be from a barcode scan or scale weight change event. This setting defaults to on.
• Fire on Cloud Triggered Measurements. Toggle this switch on to configure the webhook to be called whenever a measurement transaction is created due to a cloud trigger. This setting defaults to off.

Once saved, enVision Cloud will call your endpoint for every measurement transaction created by devices in your fleet.

Securing your webhook endpoint

It is important to verify that the originator of calls to your webhook endpoint is enVision Cloud. To handle this, calls to your endpoint will include two HTTP header values that should be used to verify that the message is authentic.

    "X-enVision-Key": "da79f8c049c1ed8808c859a909928e58",
    "X-enVision-Signature": "c1057105dea6a5a9329210be490aa6......"

The above headers are to be used in conjunction with your enVision Cloud Webhook Secret Key, available on the Webhooks screen of the enVision Cloud Portal.

The pattern used is that a nonce is sent with every message. That nonce is signed with the Secret Key to create an HMAC, which is also included with the message.

• X-enVision-Key contains the nonce value and is unique to every message
• X-enVision-Signature contains the HMAC generated by signing the nonce with the Secret Key.

To verify the authenticity of the message:

1. Generate an SHA256 HMAC of the value of X-enVision-Key signed with the Secret Key
2. Compare the hash with X-enVision-Signature. If the values are equal, the message is authentic.

//Webhook endpoint handler
[HttpPost(nameof(WebhookReceive))]
public void WebhookReceive([FromBody] object transaction)
{
    // Retrieve custom header values for validation
    string? nonce = Request.Headers["X-enVision-Key"];
    string? signature = Request.Headers["X-enVision-Signature"];

    // Ensure headers are present; if missing, exit
    if (string.IsNullOrEmpty(nonce) || string.IsNullOrEmpty(signature))
    {
        return BadRequest();
    }        

    // Key used to validate signature. Found in ECE Portal in the Webhooks Tab
    string webhookKey = "*INSERT_COMPANY_ENVISION_WEBHOOK_KEY*";

    // Validate signature and process the transaction if valid
    if (!ValidateSignature(nonce, webhookKey, signature))
    {
        Console.WriteLine("Signature mismatch.");
        // Insert error handling code
        return Unauthorized();        
    }

    Console.WriteLine($"Transaction received and verified: {transaction.ToString()}");
    // Insert code to process transaction
    return Ok();
}

 // Method to validate the received signature against a generated one
static bool ValidateSignature(string nonce, string key, string signature)
{
    return signature.Equals(GenerateHMACSHA256Signature(nonce, key));  
}

 // Generates an HMAC SHA256 signature for comparison
static string GenerateHMACSHA256Signature(string input, string key)
{
    var keyBytes = Encoding.UTF8.GetBytes(key);
    var inputBytes = Encoding.UTF8.GetBytes(input);

    var hmac = new HMACSHA256(keyBytes)
                .ComputeHash(inputBytes);
    return Convert.ToHexString().ToLower();
}