Verify Signatures

Why verify

Webhook endpoints are public URLs. Without verification, anyone who discovers your endpoint URL could send fake events. Signature verification proves that a delivery genuinely came from Bluvo.

How it works

Every webhook delivery is signed with your endpoint’s secret using HMAC-SHA256:

Bluvo concatenates the timestamp and JSON payload: ${timestamp}\n${payload}
Computes the HMAC-SHA256 of that string using your webhook secret
Base64-encodes the result and sends it in the X-Webhook-Signature header

Headers

Header	Example	Description
`X-Webhook-Signature`	`K7gNU3sdo+OL0wNhqoVWhr3g6s1xYv72ol/pe/Unols=`	Base64-encoded HMAC-SHA256 signature
`X-Webhook-Timestamp`	`1713700800000`	Unix timestamp in milliseconds when the delivery was sent

Verification example

import crypto from "node:crypto";

function verifyWebhookSignature(
  rawBody: string | Buffer,
  signature: string,
  timestamp: string,
  secret: string
): boolean {
  // 1. Reject stale deliveries (replay protection)
  const now = Date.now();
  const deliveryTime = parseInt(timestamp, 10);
  const fiveMinutes = 5 * 60 * 1000;

  if (Math.abs(now - deliveryTime) > fiveMinutes) {
    return false;
  }

  // 2. Compute expected signature
  const payload = typeof rawBody === "string" ? rawBody : rawBody.toString();
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}\n${payload}`)
    .digest("base64");

  // 3. Constant-time comparison
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

import hmac
import hashlib
import base64
import time

def verify_webhook_signature(
    raw_body: bytes,
    signature: str,
    timestamp: str,
    secret: str,
) -> bool:
    # 1. Reject stale deliveries (replay protection)
    now_ms = int(time.time() * 1000)
    delivery_time = int(timestamp)
    five_minutes = 5 * 60 * 1000

    if abs(now_ms - delivery_time) > five_minutes:
        return False

    # 2. Compute expected signature
    message = f"{timestamp}\n{raw_body.decode()}"
    expected = base64.b64encode(
        hmac.new(
            secret.encode(),
            message.encode(),
            hashlib.sha256,
        ).digest()
    ).decode()

    # 3. Constant-time comparison
    return hmac.compare_digest(signature, expected)

Timestamp validation

Bluvo does not enforce a maximum age on deliveries. We recommend your receiver rejects any payload where X-Webhook-Timestamp is more than 5 minutes from the current time. This prevents replay attacks where an attacker captures a valid delivery and resends it later.

const fiveMinutes = 5 * 60 * 1000;
if (Math.abs(Date.now() - parseInt(timestamp, 10)) > fiveMinutes) {
  return res.status(401).send("Stale delivery");
}

Secret rotation

Bluvo supports zero-downtime secret rotation with a 3-phase lifecycle:

Phase	Description
Pending	New secret created but not yet active. Deliveries are still signed with the active secret. The pending secret expires after 24 hours if not activated.
Active	The current signing secret. All new deliveries are signed with this secret.
Expired	The previous active secret. Kept for a grace period so in-flight deliveries can still be verified. The last 2 expired secrets are retained.

During rotation, verify against both the new and old secrets:

function verifyWithRotation(
  rawBody: string,
  signature: string,
  timestamp: string,
  secrets: string[]
): boolean {
  return secrets.some((secret) =>
    verifyWebhookSignature(rawBody, signature, timestamp, secret)
  );
}

To rotate a secret in the Portal:

Navigate to Settings > Webhooks and select your endpoint
Click Rotate Secret — this creates a new pending secret
Update your server with the new secret
Click Activate Secret to promote it to active

Only one pending secret is allowed at a time. You must activate or let it expire before creating another.

Common mistakes

Parsed body instead of raw body

If you parse the JSON body before computing the signature, the re-serialized string may differ from the original (key ordering, whitespace). Always use the raw request body bytes.

Wrong encoding

The signature is Base64-encoded, not hex. Make sure your HMAC output is encoded as Base64 before comparing.

String comparison instead of constant-time

Using === instead of timingSafeEqual (Node.js) or hmac.compare_digest (Python) leaks timing information that can be exploited to forge signatures.

Overview

Events

Why verify

How it works

Headers

Verification example

Timestamp validation

Secret rotation

Common mistakes

​Why verify

​How it works

​Headers

​Verification example

​Timestamp validation

​Secret rotation

​Common mistakes

Why verify

How it works

Headers

Verification example

Timestamp validation

Secret rotation

Common mistakes