HTTP Webhook Strategy - HMAC Configuration

Configure webhooks HMAC to ensure additional authentication layer.

This article applies to HTTP webhook strategy only.

With the HTTP webhook strategy active, events are sent through HTTP POST requests to the configured destination URLs. These requests can be (optionally) authenticated using HMAC (Hash-based message authentication code). By using HMAC, you can add an authentication layer and verify that the incoming data is correct and authentic.

To enable such an authentication mechanism, provide the secretKey in the HTTP configuration:

• Root secretKey – applies to deliveries that use the global HTTP destination URL and to event-specific endpoints that do not define their own secret

• Per-endpoint secretKey – secret set on an eventsConfiguration entry or on an endpoint in the Management Dashboard; when present, it overrides the root secret for that target

HMAC involves cryptographic hash function and a secret cryptographic key. SHA-256 is used as a cryptographic hash function and the provided secretKey acts as a secret cryptographic key.

The payload sent by Emporix is secured by emporix-event-signature. All the fields and the nested structures are sorted alphabetically. Also, all integer numbers are formatted as integers, not as decimals (for example, the payload contains value 1 instead of 1.0). To compute HMAC in a proper way on the receiver side, the order and format of the numbers has to be the same.

Authentication process

The steps to authenticate the message are as follows:

1. The secretKey is used to produce a key.

2. The event’s payload is converted to JSON format producing a message.

3. The SHA-256 hash function is used to produce an HMAC derived from the message and the key.

4. HMAC is encoded using Base64 scheme.

5. The encoded HMAC value is attached to the request as the emporix-event-signature header of the HTTP request.

These steps ensure that the recipient is able to verify if the request is correctly authenticated.

Example HMAC implementation

Here is an example JavaScript function which verifies incoming HTTP request on the receiver's side:

const functions = require('@google-cloud/functions-framework');
const crypto = require('crypto');
const stringify = require('json-stable-stringify');

const secretKey = 'password123';

functions.http('helloHttp', (req, res) => {

  const body = stringify(req.body); // 1
  const hmac = crypto.createHmac('sha256', secretKey); // 2
  hmac.update(body); // 3

  const computedHmac = hmac.digest('base64'); // 4

  if (computedHmac === req.headers['emporix-event-signature']) { // 5
    console.log('HMAC validation passed.'); // 6
  } else {
    console.log("HMAC validation didn't pass."); // 7
  }

  res.send(`Hello ${req.query.name || req.body.name || 'World'}!`);
});

This simple function conveys the following logic:

1. It converts the request body into JSON. The stringify function from an external library is used to order all the fields and nested objects alphabetically which allows maintaining the correct order.

2. It generates the key based on the secretKey. The secretKey is password123.

3. It generates the HMAC using SHA-256 hash function.

4. It encodes HMAC to Base64 scheme.

5. It compares the value from the emporix.event-signature header with the generated HMAC.

   • If the values match, it logs HMAC validation passed. With the above configuration, if the secretKey is set to password123 on the source side, the validation passes.

   • If the values do not match, it logs HMAC validation didn't pass. With the above configuration, if the secretKey is set to some different value than password123 on the source side, the validation doesn't pass.

This example demonstrates how you can implement HMAC in your own setup.