Webhook Setup

import crypto from "crypto";

// Per Standard Webhooks: strip the `whsec_` prefix and Base64-decode the
// remainder to obtain the raw HMAC signing key.
function getSigningKey(secret: string): Buffer {
  const trimmed = secret.startsWith("whsec_") ? secret.slice("whsec_".length) : secret;
  return Buffer.from(trimmed, "base64");
}

function computeSignature(
  secret: string,
  webhookId: string,
  webhookTimestamp: string,
  body: string | Buffer
): string {
  const payload = `${webhookId}.${webhookTimestamp}.${body.toString()}`;
  const key = getSigningKey(secret);
  const digest = crypto.createHmac("sha256", key).update(payload).digest();
  return digest.toString("base64"); // standard Base64 with padding
}

function isValidSignature(
  webhookSignatureHeader: string,
  expectedSignature: string
): boolean {
  // Header may contain multiple space-delimited entries; each is "v1,<sig>"
  const signatures = webhookSignatureHeader.split(" ");

  for (const part of signatures) {
    const [, sig] = part.split(",", 2);
    if (
      crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expectedSignature))
    ) {
      return true;
    }
  }

  return false;
}

// Example usage in an Express endpoint
import express from "express";

const app = express();

app.post(
  "/webhooks/parallel",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const webhookId = req.headers["webhook-id"] as string;
    const webhookTimestamp = req.headers["webhook-timestamp"] as string;
    const webhookSignature = req.headers["webhook-signature"] as string;
    const secret = process.env.PARALLEL_WEBHOOK_SECRET!;

    const expectedSignature = computeSignature(
      secret,
      webhookId,
      webhookTimestamp,
      req.body
    );

    if (!isValidSignature(webhookSignature, expectedSignature)) {
      return res.status(401).send("Invalid signature");
    }

    // Parse and process the webhook payload
    const payload = JSON.parse(req.body.toString());
    console.log("Webhook received:", payload);

    // Your business logic here

    res.status(200).send("OK");
  }
);

// Example for environments without Node.js crypto module

// Per Standard Webhooks: strip the `whsec_` prefix and Base64-decode the
// remainder to obtain the raw HMAC signing key.
function getSigningKey(secret: string): Uint8Array {
  const trimmed = secret.startsWith("whsec_") ? secret.slice("whsec_".length) : secret;
  const binary = atob(trimmed);
  const bytes = new Uint8Array(binary.length);
  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
  return bytes;
}

async function computeSignature(
  secret: string,
  webhookId: string,
  webhookTimestamp: string,
  body: string
): Promise<string> {
  const payload = `${webhookId}.${webhookTimestamp}.${body}`;
  const encoder = new TextEncoder();
  const key = await crypto.subtle.importKey(
    "raw",
    getSigningKey(secret),
    { name: "HMAC", hash: "SHA-256" },
    false,
    ["sign"]
  );

  const signature = await crypto.subtle.sign(
    "HMAC",
    key,
    encoder.encode(payload)
  );

  // Convert to base64
  const base64 = btoa(String.fromCharCode(...new Uint8Array(signature)));
  return base64;
}

function isValidSignature(
  webhookSignatureHeader: string,
  expectedSignature: string
): boolean {
  const signatures = webhookSignatureHeader.split(" ");

  for (const part of signatures) {
    const [, sig] = part.split(",", 2);
    if (sig === expectedSignature) {
      return true;
    }
  }

  return false;
}

// Example Cloudflare Worker
export default {
  async fetch(request: Request): Promise<Response> {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const webhookId = request.headers.get("webhook-id")!;
    const webhookTimestamp = request.headers.get("webhook-timestamp")!;
    const webhookSignature = request.headers.get("webhook-signature")!;
    const secret = "your-webhook-secret";

    const body = await request.text();

    const expectedSignature = await computeSignature(
      secret,
      webhookId,
      webhookTimestamp,
      body
    );

    if (!isValidSignature(webhookSignature, expectedSignature)) {
      return new Response("Invalid signature", { status: 401 });
    }

    const payload = JSON.parse(body);
    console.log("Webhook received:", payload);

    return new Response("OK", { status: 200 });
  },
};

import base64
import hashlib
import hmac

# Per Standard Webhooks: strip the `whsec_` prefix and Base64-decode the
# remainder to obtain the raw HMAC signing key.
def get_signing_key(secret: str) -> bytes:
    trimmed = secret[len("whsec_"):] if secret.startswith("whsec_") else secret
    return base64.b64decode(trimmed)

def compute_signature(secret: str, webhook_id: str, webhook_timestamp: str, body: bytes) -> str:
    payload = f"{webhook_id}.{webhook_timestamp}.{body.decode()}".encode()
    key = get_signing_key(secret)
    digest = hmac.new(key, payload, hashlib.sha256).digest()
    return base64.b64encode(digest).decode()  # standard Base64 with padding

def is_valid_signature(webhook_signature_header: str, expected_signature: str) -> bool:
    # Header may contain multiple space-delimited entries; each is "v1,<sig>"
    for part in webhook_signature_header.split():
        _, sig = part.split(",", 1)
        if hmac.compare_digest(sig, expected_signature):
            return True
    return False

# Example usage
webhook_secret = "your_webhook_secret_from_settings"
webhook_id = request.headers.get("webhook-id")
webhook_timestamp = request.headers.get("webhook-timestamp")
signature_header = request.headers.get("webhook-signature")
body = request.get_data()

expected_sig = compute_signature(webhook_secret, webhook_id, webhook_timestamp, body)
if is_valid_signature(signature_header, expected_sig):
    print("✓ Signature verified")
else:
    print("✗ Signature verification failed")

#!/bin/bash

# Inputs: HEADER_SIGNATURE (e.g. "v1,BASE64..."), WEBHOOK_ID, WEBHOOK_TIMESTAMP, PAYLOAD (minified JSON), SECRET
RECEIVED_SIGNATURE=$(printf "%s" "$HEADER_SIGNATURE" | cut -d',' -f2)
TO_SIGN="$WEBHOOK_ID.$WEBHOOK_TIMESTAMP.$PAYLOAD"

# Per Standard Webhooks: strip the `whsec_` prefix and Base64-decode the
# remainder to obtain the raw HMAC signing key (passed to openssl as hex).
SIGNING_KEY_HEX=$(printf "%s" "${SECRET#whsec_}" | base64 -d | xxd -p -c 256 | tr -d '\n')
EXPECTED_SIGNATURE=$(printf "%s" "$TO_SIGN" | openssl dgst -sha256 -mac HMAC -macopt "hexkey:$SIGNING_KEY_HEX" -binary | base64 | tr -d '\n')

if [ "$EXPECTED_SIGNATURE" = "$RECEIVED_SIGNATURE" ]; then
  echo "✅ Signature verification successful"
else
  echo "❌ Signature verification failed"
  exit 1
fi