Webhook Signature Verification

const crypto = require('crypto');
 
// Decode a signing secret to its key bytes: drop the 'whsec_' prefix, then base64-decode.
// Legacy secrets are exactly 64 hex characters after the prefix and decode as hex.
function decodeSecret(secret) {
  const key = secret.startsWith('whsec_') ? secret.slice(6) : secret;
  return /^[0-9a-fA-F]{64}$/.test(key) ? Buffer.from(key, 'hex') : Buffer.from(key, 'base64');
}
 
// payload: the raw request body (string or Buffer); headers: Node's lower-cased header object
function verifyWebhookSignature(payload, headers, secret, toleranceSeconds = 300) {
  const messageId = headers['webhook-id'];
  const timestamp = headers['webhook-timestamp'];
  const signatureHeader = headers['webhook-signature'];
  if (!messageId || !timestamp || !signatureHeader) {
    throw new Error('Missing webhook signature headers');
  }
 
  // 1. Verify timestamp freshness
  const now = Math.floor(Date.now() / 1000);
  if (!/^\d+$/.test(timestamp) || Math.abs(now - Number(timestamp)) > toleranceSeconds) {
    throw new Error('Webhook timestamp is too old or too far in the future');
  }
 
  // 2. Compute the expected signature over `{id}.{timestamp}.{body}`
  const expected = crypto
    .createHmac('sha256', decodeSecret(secret))
    .update(`${messageId}.${timestamp}.`)
    .update(payload)
    .digest();
 
  // 3. The header holds one or more space-separated `v1,<base64>` entries (two while a
  //    rotated secret is in its grace period). Accept if any entry matches, timing-safely.
  return signatureHeader.split(' ').some((entry) => {
    const [version, signature] = entry.split(',');
    if (version !== 'v1' || !signature) return false;
    const provided = Buffer.from(signature, 'base64');
    return provided.length === expected.length && crypto.timingSafeEqual(provided, expected);
  });
}
 
// Express.js example: keep the raw body for verification
app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  const payload = req.body; // Buffer, exactly as received
  const secret = process.env.WEBHOOK_SECRET;
 
  try {
    if (!verifyWebhookSignature(payload, req.headers, secret)) {
      return res.status(401).json({ error: 'Invalid signature' });
    }
  } catch (error) {
    return res.status(400).json({ error: error.message });
  }
 
  const event = JSON.parse(payload);
  // Process the webhook event...
 
  res.status(200).json({ received: true });
});

import base64
import hashlib
import hmac
import re
import time
from typing import Mapping, Union
 
 
def decode_secret(secret: str) -> bytes:
    """Drop the 'whsec_' prefix, then base64-decode (legacy 64-hex secrets decode as hex)."""
    key = secret[len("whsec_"):] if secret.startswith("whsec_") else secret
    if re.fullmatch(r"[0-9a-fA-F]{64}", key):
        return bytes.fromhex(key)
    return base64.b64decode(key)
 
 
def verify_webhook_signature(
    payload: Union[bytes, str],
    headers: Mapping[str, str],
    secret: str,
    tolerance_seconds: int = 300,
) -> bool:
    """
    Verify a Hookbase webhook signature.
 
    Args:
        payload: The raw request body, exactly as received
        headers: The request headers (any mapping; names are matched case-insensitively)
        secret: The endpoint's signing secret (whsec_...)
        tolerance_seconds: Maximum age of the signature (default 5 minutes)
 
    Returns:
        True if any v1 signature in the header matches
 
    Raises:
        ValueError: If a header is missing or the timestamp is outside the tolerance
    """
    h = {k.lower(): v for k, v in headers.items()}
    message_id = h.get("webhook-id")
    timestamp = h.get("webhook-timestamp")
    signature_header = h.get("webhook-signature")
    if not message_id or not timestamp or not signature_header:
        raise ValueError("Missing webhook signature headers")
 
    # 1. Verify timestamp freshness
    if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > tolerance_seconds:
        raise ValueError("Webhook timestamp is too old or too far in the future")
 
    # 2. Compute the expected signature over `{id}.{timestamp}.{body}`
    body = payload.encode("utf-8") if isinstance(payload, str) else payload
    expected = base64.b64encode(
        hmac.new(decode_secret(secret), f"{message_id}.{timestamp}.".encode() + body, hashlib.sha256).digest()
    )
 
    # 3. One or more space-separated `v1,<base64>` entries (two while a rotated secret is in its
    #    grace period): accept if any entry matches, with a timing-safe comparison
    for entry in signature_header.split(" "):
        version, _, signature = entry.partition(",")
        if version == "v1" and hmac.compare_digest(expected, signature.encode()):
            return True
    return False
 
 
# Flask example
import os
 
from flask import Flask, jsonify, request
 
app = Flask(__name__)
 
 
@app.route("/webhooks", methods=["POST"])
def handle_webhook():
    payload = request.get_data()  # raw bytes, before any JSON parsing
    secret = os.environ["WEBHOOK_SECRET"]
 
    try:
        if not verify_webhook_signature(payload, request.headers, secret):
            return jsonify({"error": "Invalid signature"}), 401
    except ValueError as e:
        return jsonify({"error": str(e)}), 400
 
    event = request.get_json()
    # Process the webhook event...
 
    return jsonify({"received": True}), 200

package main
 
import (
	"crypto/hmac"
	"crypto/sha256"
	"crypto/subtle"
	"encoding/base64"
	"encoding/hex"
	"errors"
	"fmt"
	"io"
	"math"
	"net/http"
	"os"
	"regexp"
	"strconv"
	"strings"
	"time"
)
 
// Legacy signing secrets are exactly 64 hex characters; current ones are base64.
var legacyHexSecret = regexp.MustCompile(`^[0-9a-fA-F]{64}$`)
 
// decodeSecret drops the "whsec_" prefix and decodes the rest to the HMAC key bytes.
func decodeSecret(secret string) ([]byte, error) {
	key := strings.TrimPrefix(secret, "whsec_")
	if legacyHexSecret.MatchString(key) {
		return hex.DecodeString(key)
	}
	return base64.StdEncoding.DecodeString(key)
}
 
// VerifyWebhookSignature verifies a Hookbase webhook signature. It returns nil if any v1
// signature in the webhook-signature header matches.
func VerifyWebhookSignature(payload []byte, headers http.Header, secret string, toleranceSeconds int64) error {
	messageID := headers.Get("webhook-id")
	timestampStr := headers.Get("webhook-timestamp")
	signatureHeader := headers.Get("webhook-signature")
	if messageID == "" || timestampStr == "" || signatureHeader == "" {
		return errors.New("missing webhook signature headers")
	}
 
	// 1. Verify timestamp freshness
	timestamp, err := strconv.ParseInt(timestampStr, 10, 64)
	if err != nil {
		return errors.New("invalid timestamp format")
	}
	if math.Abs(float64(time.Now().Unix()-timestamp)) > float64(toleranceSeconds) {
		return errors.New("webhook timestamp is too old or too far in the future")
	}
 
	// 2. Compute the expected signature over `{id}.{timestamp}.{body}`
	secretBytes, err := decodeSecret(secret)
	if err != nil {
		return fmt.Errorf("invalid secret format: %w", err)
	}
	mac := hmac.New(sha256.New, secretBytes)
	mac.Write([]byte(messageID + "." + timestampStr + "."))
	mac.Write(payload)
	expected := []byte(base64.StdEncoding.EncodeToString(mac.Sum(nil)))
 
	// 3. One or more space-separated "v1,<base64>" entries (two while a rotated secret is in
	//    its grace period): accept if any entry matches, with a timing-safe comparison
	for _, entry := range strings.Split(signatureHeader, " ") {
		version, signature, ok := strings.Cut(entry, ",")
		if ok && version == "v1" && subtle.ConstantTimeCompare(expected, []byte(signature)) == 1 {
			return nil
		}
	}
	return errors.New("signature mismatch")
}
 
// HTTP handler example
func webhookHandler(w http.ResponseWriter, r *http.Request) {
	payload, err := io.ReadAll(r.Body)
	if err != nil {
		http.Error(w, "Failed to read body", http.StatusBadRequest)
		return
	}
 
	secret := os.Getenv("WEBHOOK_SECRET")
 
	if err := VerifyWebhookSignature(payload, r.Header, secret, 300); err != nil {
		http.Error(w, err.Error(), http.StatusUnauthorized)
		return
	}
 
	// Process the webhook event...
 
	w.WriteHeader(http.StatusOK)
	w.Write([]byte(`{"received": true}`))
}

require 'openssl'
require 'base64'
require 'json'
 
module Hookbase
  class SignatureError < StandardError; end
 
  class WebhookVerifier
    TOLERANCE_SECONDS = 300
 
    def initialize(secret)
      # Drop the 'whsec_' prefix, then base64-decode (legacy 64-hex secrets decode as hex)
      key = secret.delete_prefix('whsec_')
      @secret_bytes = key.match?(/\A\h{64}\z/) ? [key].pack('H*') : Base64.strict_decode64(key)
    end
 
    # headers: Rails' request.headers, or any hash with the header names
    def verify!(payload, headers, tolerance_seconds: TOLERANCE_SECONDS)
      message_id = header(headers, 'webhook-id')
      timestamp = header(headers, 'webhook-timestamp')
      signature_header = header(headers, 'webhook-signature')
      raise SignatureError, 'Missing webhook signature headers' unless message_id && timestamp && signature_header
 
      # 1. Verify timestamp freshness
      unless timestamp.match?(/\A\d+\z/) && (Time.now.to_i - timestamp.to_i).abs <= tolerance_seconds
        raise SignatureError, 'Webhook timestamp is too old or too far in the future'
      end
 
      # 2. Compute the expected signature over `{id}.{timestamp}.{body}`
      expected = Base64.strict_encode64(
        OpenSSL::HMAC.digest('sha256', @secret_bytes, "#{message_id}.#{timestamp}.#{payload}")
      )
 
      # 3. One or more space-separated `v1,<base64>` entries (two while a rotated secret is in
      #    its grace period): accept if any entry matches, with a timing-safe comparison
      matched = signature_header.split(' ').any? do |entry|
        version, signature = entry.split(',', 2)
        version == 'v1' && signature && OpenSSL.fixed_length_secure_compare(expected, signature)
      rescue ArgumentError # different length
        false
      end
      raise SignatureError, 'Signature mismatch' unless matched
 
      true
    end
 
    private
 
    def header(headers, name)
      headers[name] || headers["HTTP_#{name.upcase.tr('-', '_')}"]
    end
  end
end
 
# Rails controller example
class WebhooksController < ApplicationController
  skip_before_action :verify_authenticity_token
 
  def create
    payload = request.raw_post
    verifier = Hookbase::WebhookVerifier.new(ENV.fetch('WEBHOOK_SECRET'))
 
    begin
      verifier.verify!(payload, request.headers)
 
      event = JSON.parse(payload)
      # Process the webhook event...
 
      render json: { received: true }, status: :ok
    rescue Hookbase::SignatureError => e
      render json: { error: e.message }, status: :unauthorized
    end
  end
end

<?php
 
class HookbaseWebhookVerifier
{
    private string $secretBytes;
    private int $toleranceSeconds;
 
    public function __construct(string $secret, int $toleranceSeconds = 300)
    {
        // Drop the 'whsec_' prefix, then base64-decode (legacy 64-hex secrets decode as hex)
        $key = str_starts_with($secret, 'whsec_') ? substr($secret, 6) : $secret;
        $bytes = preg_match('/^[0-9a-fA-F]{64}$/', $key) ? hex2bin($key) : base64_decode($key, true);
        if ($bytes === false) {
            throw new InvalidArgumentException('Invalid signing secret');
        }
        $this->secretBytes = $bytes;
        $this->toleranceSeconds = $toleranceSeconds;
    }
 
    /**
     * Verify a Hookbase webhook signature
     *
     * @param string $payload The raw request body
     * @param array $headers Request headers, e.g. getallheaders() (names are matched case-insensitively)
     * @return bool True if valid
     * @throws InvalidArgumentException If verification fails
     */
    public function verify(string $payload, array $headers): bool
    {
        $headers = array_change_key_case($headers, CASE_LOWER);
        $messageId = $headers['webhook-id'] ?? '';
        $timestamp = $headers['webhook-timestamp'] ?? '';
        $signatureHeader = $headers['webhook-signature'] ?? '';
        if ($messageId === '' || $timestamp === '' || $signatureHeader === '') {
            throw new InvalidArgumentException('Missing webhook signature headers');
        }
 
        // 1. Verify timestamp freshness
        if (!ctype_digit($timestamp) || abs(time() - (int) $timestamp) > $this->toleranceSeconds) {
            throw new InvalidArgumentException('Webhook timestamp is too old or too far in the future');
        }
 
        // 2. Compute the expected signature over `{id}.{timestamp}.{body}`
        $expected = base64_encode(
            hash_hmac('sha256', "{$messageId}.{$timestamp}.{$payload}", $this->secretBytes, true)
        );
 
        // 3. One or more space-separated `v1,<base64>` entries (two while a rotated secret is in
        //    its grace period): accept if any entry matches, with a timing-safe comparison
        foreach (explode(' ', $signatureHeader) as $entry) {
            $parts = explode(',', $entry, 2);
            if (count($parts) === 2 && $parts[0] === 'v1' && hash_equals($expected, $parts[1])) {
                return true;
            }
        }
 
        throw new InvalidArgumentException('Signature mismatch');
    }
}
 
// Usage example
$payload = file_get_contents('php://input');
$verifier = new HookbaseWebhookVerifier(getenv('WEBHOOK_SECRET'));
 
try {
    $verifier->verify($payload, getallheaders());
 
    $event = json_decode($payload, true);
    // Process the webhook event...
 
    http_response_code(200);
    echo json_encode(['received' => true]);
} catch (InvalidArgumentException $e) {
    http_response_code(401);
    echo json_encode(['error' => $e->getMessage()]);
}

import app.hookbase.errors.WebhookVerificationException;
import app.hookbase.webhooks.Webhook;
import com.fasterxml.jackson.databind.JsonNode;
import com.sun.net.httpserver.HttpServer;
import java.io.InputStream;
import java.net.InetSocketAddress;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
 
public class WebhookServer {
    public static void main(String[] args) throws Exception {
        // Accepts whsec_ secrets (base64 or legacy hex)
        Webhook webhook = new Webhook(System.getenv("WEBHOOK_SECRET"));
 
        HttpServer server = HttpServer.create(new InetSocketAddress(3000), 0);
        server.createContext("/webhooks", exchange -> {
            // 1. Read the raw body as bytes, exactly as received
            byte[] body;
            try (InputStream in = exchange.getRequestBody()) {
                body = in.readAllBytes();
            }
 
            // 2. Collect the headers (names are matched case-insensitively)
            Map<String, String> headers = new LinkedHashMap<>();
            for (Map.Entry<String, List<String>> h : exchange.getRequestHeaders().entrySet()) {
                headers.put(h.getKey(), h.getValue().getFirst());
            }
 
            int status;
            try {
                // 3. Checks the timestamp (5 minute tolerance) and every v1 signature,
                //    with a constant-time comparison, then parses the JSON body
                JsonNode event = webhook.verify(body, headers);
                // Process the webhook event...
                status = 200;
            } catch (WebhookVerificationException e) {
                status = 401;
            }
            exchange.sendResponseHeaders(status, -1);
            exchange.close();
        });
        server.start();
    }
}

curl -X POST https://api.hookbase.app/api/organizations/{orgId}/webhook-endpoints \
  -H "Authorization: Bearer $HOOKBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"applicationId": "<application id>", "url": "https://example.com/webhooks", "signatureScheme": "ed25519"}'
# → { "data": { "id": "...", "signatureScheme": "ed25519", "publicKey": "whpk_...", ... } }

import { createPublicKey, verify } from 'node:crypto';
 
const PUBLIC_KEY = process.env.HOOKBASE_PUBLIC_KEY; // whpk_...
const key = createPublicKey({
  key: { kty: 'OKP', crv: 'Ed25519', x: Buffer.from(PUBLIC_KEY.slice(5), 'base64').toString('base64url') },
  format: 'jwk',
});
 
// rawBody: the request body exactly as received (a string, before JSON.parse)
export function verifyWebhook(rawBody, headers, toleranceSeconds = 300) {
  const id = headers['webhook-id'];
  const timestamp = headers['webhook-timestamp'];
  const signatures = headers['webhook-signature'];
  if (!id || !timestamp || !signatures) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSeconds) return false;
 
  const content = Buffer.from(`${id}.${timestamp}.${rawBody}`);
  return signatures.split(' ').some((entry) => {
    const [version, signature] = entry.split(',');
    return version === 'v1a' && !!signature && verify(null, content, key, Buffer.from(signature, 'base64'));
  });
}

import base64
import os
import time
 
from cryptography.exceptions import InvalidSignature
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
 
PUBLIC_KEY = os.environ["HOOKBASE_PUBLIC_KEY"]  # whpk_...
key = Ed25519PublicKey.from_public_bytes(base64.b64decode(PUBLIC_KEY.removeprefix("whpk_")))
 
 
def verify_webhook(raw_body: bytes, headers, tolerance_seconds: int = 300) -> bool:
    msg_id = headers.get("webhook-id")
    timestamp = headers.get("webhook-timestamp")
    signatures = headers.get("webhook-signature")
    if not msg_id or not timestamp or not signatures:
        return False
    if abs(time.time() - int(timestamp)) > tolerance_seconds:
        return False
 
    content = f"{msg_id}.{timestamp}.".encode() + raw_body
    for entry in signatures.split(" "):
        version, _, signature = entry.partition(",")
        if version != "v1a":
            continue
        try:
            key.verify(base64.b64decode(signature), content)
            return True
        except (InvalidSignature, ValueError):
            continue
    return False

package webhooks
 
import (
	"crypto/ed25519"
	"encoding/base64"
	"math"
	"net/http"
	"strconv"
	"strings"
	"time"
)
 
// publicKey is the endpoint's whpk_ key with the prefix removed, base64-decoded (32 bytes).
func VerifyV1a(publicKey ed25519.PublicKey, rawBody []byte, h http.Header) bool {
	id, ts, sigs := h.Get("webhook-id"), h.Get("webhook-timestamp"), h.Get("webhook-signature")
	t, err := strconv.ParseInt(ts, 10, 64)
	if id == "" || sigs == "" || err != nil || math.Abs(float64(time.Now().Unix()-t)) > 300 {
		return false
	}
	content := []byte(id + "." + ts + "." + string(rawBody))
	for _, entry := range strings.Split(sigs, " ") {
		version, sig, ok := strings.Cut(entry, ",")
		if !ok || version != "v1a" {
			continue
		}
		if raw, err := base64.StdEncoding.DecodeString(sig); err == nil && ed25519.Verify(publicKey, content, raw) {
			return true
		}
	}
	return false
}

import java.nio.charset.StandardCharsets;
import java.security.GeneralSecurityException;
import java.security.KeyFactory;
import java.security.PublicKey;
import java.security.Signature;
import java.security.spec.X509EncodedKeySpec;
import java.util.Base64;
import java.util.HexFormat;
import java.util.Map;
 
public final class WebhookV1a {
    // DER prefix that wraps a raw 32-byte Ed25519 key as an X.509 SubjectPublicKeyInfo
    private static final byte[] ED25519_SPKI_PREFIX = HexFormat.of().parseHex("302a300506032b6570032100");
 
    private final PublicKey key;
 
    /** publicKey: the endpoint's whpk_... key */
    public WebhookV1a(String publicKey) throws GeneralSecurityException {
        byte[] raw = Base64.getDecoder().decode(publicKey.substring("whpk_".length()));
        byte[] spki = new byte[ED25519_SPKI_PREFIX.length + raw.length];
        System.arraycopy(ED25519_SPKI_PREFIX, 0, spki, 0, ED25519_SPKI_PREFIX.length);
        System.arraycopy(raw, 0, spki, ED25519_SPKI_PREFIX.length, raw.length);
        key = KeyFactory.getInstance("Ed25519").generatePublic(new X509EncodedKeySpec(spki));
    }
 
    /** rawBody: the request body exactly as received; headers: lower-case names */
    public boolean verify(byte[] rawBody, Map<String, String> headers) {
        String id = headers.get("webhook-id");
        String timestamp = headers.get("webhook-timestamp");
        String signatures = headers.get("webhook-signature");
        if (id == null || timestamp == null || signatures == null) return false;
        try {
            if (Math.abs(System.currentTimeMillis() / 1000 - Long.parseLong(timestamp)) > 300) return false;
        } catch (NumberFormatException e) {
            return false;
        }
 
        byte[] prefix = (id + "." + timestamp + ".").getBytes(StandardCharsets.UTF_8);
        for (String entry : signatures.split(" ")) {
            String[] parts = entry.split(",", 2);
            if (parts.length != 2 || !parts[0].equals("v1a")) continue;
            try {
                Signature verifier = Signature.getInstance("Ed25519");
                verifier.initVerify(key);
                verifier.update(prefix);
                verifier.update(rawBody);
                if (verifier.verify(Base64.getDecoder().decode(parts[1]))) return true;
            } catch (GeneralSecurityException | IllegalArgumentException e) {
                // malformed entry: try the next one
            }
        }
        return false;
    }
}