How to Verify a Webhook

All requests made by Bolt to your ecommerce Merchant Callback API will be signed to ensure the authenticity of our requests. Your implementation should always verify the signature to make sure that it's always Bolt calling your endpoint.

Bolt signs the payload and includes the HMAC signature in the request header X-Bolt-Hmac-Sha256. Use the following steps to verify the payload with this signature.

Step 1: Get Signing Secret

1. Log in to your Bolt Merchant Dashboard.
2. Navigate to Administration > API.
3. Scroll to Signing Secret.

Step 2: Use Secret for Verification

Bolt signs the payload with HMAC SHA-256, using the signing secret as the key, and Base64 encodes the result so it travels as plain text. Compute the same value and compare it to the header:

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.