`blursec.webhooks`

Verify HMAC-SHA256-signed deliveries Blursec posts to your endpoint. A credential or session can come back clean at login and only show up in a stealer-log batch hours or days later. Webhooks are how Blursec tells you about those after-the-fact compromises (e.g. session.compromised, credential.leaked) so you can revoke proactively instead of waiting for the next check. Verification is local — it never round-trips to the Blursec API, so it works in any runtime and adds no latency to your handler.

import { Blursec } from "@blursec/sdk";

const blursec = new Blursec({ apiKey: process.env.BLURSEC_API_KEY! });

`verify(options) → Promise<boolean>`

Returns true only when both the signature is valid and the delivery falls inside the replay window. Returns false for any malformed or stale delivery — it never throws on a bad delivery, so a misbehaving sender can’t crash your handler. It throws BlursecValidationError only when secret is empty (caller misconfiguration).

Pass the raw request body. The signature is computed over the exact bytes Blursec sent. Any JSON re-serialization or whitespace normalization by your framework will invalidate it — use a raw-body parser on the webhook route.

import express from "express";

app.post(
  "/webhooks/blursec",
  express.raw({ type: "*/*" }),          // raw bytes, not express.json()
  async (req, res) => {
    const ok = await blursec.webhooks.verify({
      secret: process.env.BLURSEC_WEBHOOK_SECRET!,
      payload: req.body,                 // Buffer of the exact bytes
      signature: req.header("X-Blursec-Signature") ?? "",
      timestamp: req.header("X-Blursec-Timestamp") ?? "",
    });

    if (!ok) return res.status(401).end();

    const event = JSON.parse(req.body.toString("utf8"));
    // ...handle event.type: "session.compromised", "credential.leaked", ...
    res.status(204).end();
  },
);

`VerifyWebhookOptions`

interface VerifyWebhookOptions {
  secret: string;                                  // shared webhook secret
  payload: string | Uint8Array | ArrayBuffer;      // raw, unparsed body bytes
  signature: string;                               // X-Blursec-Signature (hex, optional "sha256=" prefix)
  timestamp: string | number;                      // X-Blursec-Timestamp (Unix epoch ms)
  toleranceMs?: number;                            // replay window; default 5 min
}

Delivery headers

Blursec sets these headers on every delivery. They’re also exported as a typed bag (BLURSEC_WEBHOOK_HEADERS) and surfaced on blursec.webhooks.headerNames so framework adapters wire them up consistently:

Header	Meaning
`X-Blursec-Signature`	`sha256=<hex>` HMAC of the body + timestamp
`X-Blursec-Timestamp`	Unix epoch milliseconds of the delivery
`X-Blursec-Delivery`	Unique id for this delivery (idempotency key)
`X-Blursec-Event`	Semantic event name, e.g. `session.compromised`

The default replay-protection window is 5 minutes (DEFAULT_WEBHOOK_TOLERANCE_MS, also on blursec.webhooks.defaultToleranceMs). Override it per call with toleranceMs.

Standalone verification (no client)

verify is a thin wrapper over the exported verifyWebhookSignature helper. Use the helper directly in an edge handler that doesn’t otherwise need a BlursecClient:

import {
  verifyWebhookSignature,
  BLURSEC_WEBHOOK_HEADERS,
} from "@blursec/sdk";

export default async function handler(req: Request): Promise<Response> {
  const body = await req.text();
  const ok = await verifyWebhookSignature({
    secret: BLURSEC_WEBHOOK_SECRET,
    payload: body,
    signature: req.headers.get(BLURSEC_WEBHOOK_HEADERS.signature) ?? "",
    timestamp: req.headers.get(BLURSEC_WEBHOOK_HEADERS.timestamp) ?? "",
  });
  return new Response(null, { status: ok ? 204 : 401 });
}

For tests, signWebhookPayload(...) produces a valid signature for a given secret + payload + timestamp so you can exercise your handler end-to-end.

Getting started

Resources

Webhooks

`blursec.webhooks`

`verify(options) → Promise<boolean>`

`VerifyWebhookOptions`

Delivery headers

Standalone verification (no client)

​blursec.webhooks

​verify(options) → Promise<boolean>

​VerifyWebhookOptions

​Delivery headers

​Standalone verification (no client)

`blursec.webhooks`

`verify(options) → Promise<boolean>`

`VerifyWebhookOptions`

Delivery headers

Standalone verification (no client)