Validate Webhook Authenticity

1. Configure a Webhook Endpoint

In your Bolt Merchant account:

• In the left-side menu, go to Administration → Webhooks.
• Enter the URL of the endpoint on your server that will receive webhook requests.

2. Get Your Signing Secret

In your Bolt Merchant account:

• In the left-side menu, go to Administration → API.
• Copy the Signing Secret. You will need it to validate requests.

3. Validate Incoming Webhooks

Each webhook request includes a signature in the X-Bolt-Hmac-Sha256 header. To verify the request:

• Take the raw request body.
• Hash it with your Signing Secret using HMAC + SHA-256.
• Base64-encode the result.
• Compare it to the signature in the header. If they match, the webhook is valid.

import { createHmac, timingSafeEqual } from "node:crypto";

export function isFromBolt(
  rawBody: Buffer,
  headerValue: string,
  signingSecret: string,
): boolean {
  const expected = createHmac("sha256", signingSecret).update(rawBody).digest("base64");
  const a = Buffer.from(expected);
  const b = Buffer.from(headerValue);
  // timingSafeEqual throws unless both buffers are the same length.
  return a.length === b.length && timingSafeEqual(a, b);
}

Pass the raw request body exactly as received. Parsing and re-serializing the JSON first changes the bytes, and the signature will not match. headerValue is the value of the X-Bolt-Hmac-Sha256 header; read it the way your framework exposes headers, which is usually lowercased.