> ## Documentation Index
> Fetch the complete documentation index at: https://sendmux.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Verify webhook signatures

> Verify the HMAC-SHA256 signature on every Qubrics webhook delivery.

Every webhook POST includes `X-Qubrics-Signature-V2: v1=<hex>` and `X-Qubrics-Timestamp: <Unix seconds>`. Verify the signature and timestamp before processing the event. The legacy `X-Qubrics-Signature: sha256=<hex>` header remains available.

## What to sign

* Use the webhook signing secret returned when the subscription was created or rotated.
* Join `X-Qubrics-Timestamp`, a literal full stop (`.`), and the raw request body bytes.
* Compute HMAC-SHA256 and compare it with `v1` in constant time.
* Reject timestamps outside your freshness window. The example accepts at most 300 seconds of clock difference in either direction.

Each retry has a fresh timestamp and signature. Its event ID and body stay unchanged. After verification, deduplicate by the signed body's `id`; freshness checks do not prevent duplicates within the accepted window.

> [!WARNING]
>
> Do not parse and re-serialise the JSON before verification. That can change
> whitespace or field order and break the signature check.

## Example verifier

```js theme={null}
const encoder = new TextEncoder();

export async function verifyQubricsWebhook(request, secret) {
  const received = request.headers.get("X-Qubrics-Signature-V2") ?? "";
  const timestampHeader = request.headers.get("X-Qubrics-Timestamp") ?? "";
  const match = /^v1=([a-f0-9]{64})$/.exec(received);
  if (!match || !/^[0-9]{1,10}$/.test(timestampHeader)) return { ok: false };

  const timestamp = Number(timestampHeader);
  if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > 300) {
    return { ok: false };
  }

  const rawBody = new Uint8Array(await request.arrayBuffer());
  const prefix = encoder.encode(`${timestampHeader}.`);
  const signed = new Uint8Array(prefix.length + rawBody.length);
  signed.set(prefix);
  signed.set(rawBody, prefix.length);
  const signature = Uint8Array.from(match[1].match(/../g), (hex) =>
    Number.parseInt(hex, 16),
  );
  const key = await crypto.subtle.importKey(
    "raw",
    encoder.encode(secret),
    { name: "HMAC", hash: "SHA-256" },
    false,
    ["verify"],
  );
  if (!(await crypto.subtle.verify("HMAC", key, signature, signed))) {
    return { ok: false };
  }

  try {
    const body = JSON.parse(
      new TextDecoder("utf-8", { fatal: true }).decode(rawBody),
    );
    if (
      !body ||
      typeof body.id !== "string" ||
      typeof body.type !== "string" ||
      body.id !== request.headers.get("X-Qubrics-Event-Id") ||
      body.type !== request.headers.get("X-Qubrics-Event-Type")
    )
      return { ok: false };
    return { ok: true, body, eventId: body.id, eventType: body.type };
  } catch {
    return { ok: false };
  }
}
```

## Common mistakes

* Reading parsed JSON instead of the raw body.
* Verifying only the body instead of the timestamp and body together.
* Accepting stale timestamps or keeping an inaccurate server clock.
* Using a normal string comparison for secrets.
* Processing retries without deduplicating the verified event ID.

## Legacy verification

The legacy `X-Qubrics-Signature` value is `sha256=<hex HMAC-SHA256>` over the raw body bytes alone, using the same secret. It has no signed timestamp. Existing verifiers keep working; use V2 for freshness checks. A receiver configured for V2 should reject a missing or invalid V2 header instead of falling back to legacy verification.

## Endpoint behaviour

Return a `2xx` status once the event is accepted. For longer processing, store the event first, return quickly, and process it after the response.

Qubrics retries non-`2xx` responses and timeouts. See [Webhooks setup](https://sendmux.ai/docs/webhooks/setup.md#retries).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.