# HTTP Webhook Strategy - HMAC Configuration

{% hint style="info" %}
This article applies to **HTTP webhook strategy** only.
{% endhint %}

With the HTTP webhook strategy `active`, all the events are sent to the configured `destinationURL` through HTTP `POST` requests. These requests can be (optionally) authenticated using **HMAC** (Hash-based message authentication code). By using HMAC, you can add 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.

**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.

{% hint style="warning" %}
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.
{% endhint %}

## 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:

```js

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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.emporix.io/ce/system-management/webhooks-user-guide/hmac-configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.