Webhook Signature

Calculating the Signature Hash

When Bessy sends a webhook, it includes a signature hash in the request headers, typically under the header x-signature. This signature is generated using the HMAC-SHA256 algorithm and combines your unique API key with the body of the request.

Here is the code to calculate the signature hash:

const crypto = require("crypto"); // Import the cryptography module
const apiKey = "your_api_key";    // Your unique API key
const bodyAsString = JSON.stringify(body); // Convert the body of the webhook to a string
const sha256Hasher = crypto.createHmac("sha256", apiKey); // Create an HMAC-SHA256 hasher
const signature = sha256Hasher.update(bodyAsString).digest("hex"); // Generate the hash

Explanation of the Code:

1. Convert the body to a string:
   The body of the webhook (payload) is serialized into a JSON string using JSON.stringify(body). This ensures the data is consistent for both Bessy and your application.

2. Create the HMAC generator:
   Using crypto.createHmac("sha256", apiKey), an HMAC generator is created with the sha256 algorithm and your unique apiKey as the secret key.

3. Generate the hash:
   The .update(bodyAsString) applies the HMAC to the webhook payload.
   The .digest("hex") outputs the resulting hash in hexadecimal format. This is the signature you will compare against the one provided by Bessy.

Why Is Signature Verification Important?

• Authentication:
  Verification ensures that the webhook is sent by Bessy and not a third party.

• Integrity:
  It confirms that the content of the webhook payload has not been altered during transmission. Any modification would result in a mismatched signature.

• Security:
  This method protects your application from malicious actors attempting to send forged or manipulated webhook requests.