Documentation

Webhook signatures

Verify that webhook payloads are genuinely from BXLivechat.

How it works

Every webhook POST request includes an X-BXLivechat-Signature header. This header contains an HMAC-SHA256 hash of the raw request body, signed with the webhook secret you received when creating the webhook.

Verifying signatures

Node.js

const crypto = require("crypto");

function verifySignature(rawBody, secret, signatureHeader) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(signatureHeader, "hex")
  );
}

Python

import hmac
import hashlib

def verify_signature(raw_body: bytes, secret: str, signature_header: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        raw_body,
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(expected, signature_header)

Step by step

Extract the X-BXLivechat-Signature header from the incoming request.
Read the raw request body as bytes — do not parse it as JSON first.
Compute the HMAC-SHA256 of the raw body using your webhook secret.
Compare the computed hash to the header value using a timing-safe comparison function.
Reject the request with 401 Unauthorized if the signatures do not match.

Example middleware

An Express.js middleware that verifies every incoming webhook request:

const crypto = require("crypto");

const WEBHOOK_SECRET = process.env.BXLIVECHAT_WEBHOOK_SECRET;

function webhookVerification(req, res, next) {
  const signature = req.headers["x-bxlivechat-signature"];
  if (!signature) {
    return res.status(401).json({ error: "Missing signature header" });
  }

  const expected = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(req.rawBody)
    .digest("hex");

  const isValid = crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(signature, "hex")
  );

  if (!isValid) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  next();
}

// Usage: app.post("/webhooks/bxlivechat", webhookVerification, handler);

Always verify — Never skip signature verification in production. An attacker could forge webhook payloads to inject false data into your system.

Rotating secrets

If your webhook secret is compromised, you can rotate it without downtime:

Navigate to Admin → Webhooks.
Click the webhook you want to update.
Click Edit → Regenerate secret.
Copy the new secret and update your server configuration.
The old secret remains valid for 1 hour to give you time to deploy the new secret.

Events Widget SDK