Verify webhook signatures

Every webhook delivery is signed using the secret_key returned at webhook creation time. Verify the signature on your server before acting on the payload.

How signing works

BugSmash signs each delivery using HMAC-SHA256 over a string that combines the timestamp and the raw JSON payload:

signed_payload = `${X-Webhook-Timestamp}.${raw_request_body}`
signature      = HMAC_SHA256(secret_key, signed_payload)

The resulting hex-encoded signature is sent in the X-BugSmash-Signature header. The Unix timestamp used during signing is sent in the X-Webhook-Timestamp header.

Always compare signatures using a constant-time function (e.g. crypto.timingSafeEqual in Node.js) to avoid timing attacks.

Request headers BugSmash sends

{
  "user-agent": "GuzzleHttp/7",
  "content-length": "971",
  "accept": "application/json",
  "content-type": "application/json",
  "x-bugsmash-signature": "<HMAC-SHA256 hex digest>",
  "x-webhook-timestamp": "1777121034",
  "accept-encoding": "gzip"
}

string

Unix timestamp (in seconds) of when the payload was signed.

string

Hex-encoded HMAC-SHA256 signature.

Verifying the signature

Node.js

const crypto = require("crypto");

function verifyWebhookSignature({
  secretKey,           // The secret_key returned at webhook creation
  payload,             // The parsed JSON body
  receivedTimestamp,   // value of X-Webhook-Timestamp header
  receivedSignature,   // value of X-BugSmash-Signature header
}) {
  // 1. Build the signed payload exactly as BugSmash did
  const signedPayload = `${receivedTimestamp}.${JSON.stringify(payload)}`;

  // 2. Compute the expected signature
  const expectedSignature = crypto
    .createHmac("sha256", secretKey)
    .update(signedPayload)
    .digest("hex");

  // 3. Compare in constant time
  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature),
    Buffer.from(receivedSignature),
  );
}

Some frameworks reformat the JSON body before it reaches your handler, which changes the bytes and invalidates the signature. If verification fails unexpectedly, sign against the raw request body rather than a re-serialized object.

Replay protection

The X-Webhook-Timestamp header lets you reject deliveries that are too old. A common rule is to ignore any request older than five minutes:

const fiveMinutes = 5 * 60;
const now = Math.floor(Date.now() / 1000);
if (Math.abs(now - Number(receivedTimestamp)) > fiveMinutes) {
  return res.status(400).send("Stale webhook");
}

Folders

Versions

Projects

Comments

Webhooks

Verify webhook signatures

How signing works

Request headers BugSmash sends

Verifying the signature

Replay protection

​How signing works

​Request headers BugSmash sends

​Verifying the signature

​Replay protection

How signing works

Request headers BugSmash sends

Verifying the signature

Replay protection