Verifying Signatures

import crypto from 'node:crypto'

const TOLERANCE_SECONDS = 5 * 60

// rawBody: the request body as a Buffer, before JSON parsing
// (with Express: app.post('/webhooks', express.raw({ type: 'application/json' }), ...))
export function verifyWebhook(rawBody, headers, secret) {
  const id = headers['webhook-id']
  const timestamp = headers['webhook-timestamp']
  const signatures = headers['webhook-signature']
  if (!id || !timestamp || !signatures) throw new Error('Missing webhook headers')

  const ts = Number(timestamp)
  const now = Math.floor(Date.now() / 1000)
  if (!Number.isInteger(ts) || Math.abs(now - ts) > TOLERANCE_SECONDS) {
    throw new Error('Timestamp outside the tolerance')
  }

  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64')
  const expected = crypto
    .createHmac('sha256', key)
    .update(`${id}.${timestamp}.`)
    .update(rawBody)
    .digest()

  for (const entry of signatures.split(' ')) {
    const [version, signature] = entry.split(',')
    if (version !== 'v1' || !signature) continue
    const given = Buffer.from(signature, 'base64')
    if (given.length === expected.length && crypto.timingSafeEqual(given, expected)) {
      return JSON.parse(rawBody.toString('utf8'))
    }
  }
  throw new Error('No matching signature')
}

# Python 3.9 or later
import base64
import hashlib
import hmac
import json
import time

TOLERANCE_SECONDS = 5 * 60

def verify_webhook(raw_body: bytes, headers, secret: str):
    """raw_body: the request body as bytes, before JSON parsing."""
    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:
        raise ValueError("Missing webhook headers")

    try:
        ts = int(timestamp)
    except ValueError:
        raise ValueError("Invalid timestamp")
    if abs(int(time.time()) - ts) > TOLERANCE_SECONDS:
        raise ValueError("Timestamp outside the tolerance")

    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{msg_id}.{timestamp}.".encode() + raw_body
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()

    for entry in signatures.split(" "):
        version, _, signature = entry.partition(",")
        if version == "v1" and hmac.compare_digest(signature, expected):
            return json.loads(raw_body)
    raise ValueError("No matching signature")

<?php

const TOLERANCE_SECONDS = 300;

/**
 * $rawBody: file_get_contents('php://input'), before json_decode.
 * $headers: lower-case header names, e.g. from getallheaders() normalised.
 */
function verifyWebhook(string $rawBody, array $headers, string $secret): array
{
    $id = $headers['webhook-id'] ?? '';
    $timestamp = $headers['webhook-timestamp'] ?? '';
    $signatures = $headers['webhook-signature'] ?? '';
    if ($id === '' || $timestamp === '' || $signatures === '') {
        throw new RuntimeException('Missing webhook headers');
    }

    if (!ctype_digit($timestamp) || abs(time() - (int) $timestamp) > TOLERANCE_SECONDS) {
        throw new RuntimeException('Timestamp outside the tolerance');
    }

    $key = base64_decode(preg_replace('/^whsec_/', '', $secret), true);
    $expected = base64_encode(hash_hmac('sha256', "{$id}.{$timestamp}.{$rawBody}", $key, true));

    foreach (explode(' ', $signatures) as $entry) {
        [$version, $signature] = array_pad(explode(',', $entry, 2), 2, '');
        if ($version === 'v1' && hash_equals($expected, $signature)) {
            return json_decode($rawBody, true, 512, JSON_THROW_ON_ERROR);
        }
    }
    throw new RuntimeException('No matching signature');
}

# Ruby 2.6 or later
require "base64"
require "json"
require "openssl"

TOLERANCE_SECONDS = 5 * 60

# raw_body: request.raw_post (Rails) or request.body.read (Rack), before JSON parsing
def verify_webhook(raw_body, headers, secret)
  id = headers["webhook-id"]
  timestamp = headers["webhook-timestamp"]
  signatures = headers["webhook-signature"]
  raise "Missing webhook headers" if [id, timestamp, signatures].any? { |v| v.nil? || v.empty? }

  ts = Integer(timestamp, exception: false)
  raise "Timestamp outside the tolerance" if ts.nil? || (Time.now.to_i - ts).abs > TOLERANCE_SECONDS

  key = Base64.strict_decode64(secret.delete_prefix("whsec_"))
  digest = OpenSSL::HMAC.digest("SHA256", key, "#{id}.#{timestamp}.#{raw_body}")
  expected = Base64.strict_encode64(digest)

  signatures.split(" ").each do |entry|
    version, signature = entry.split(",", 2)
    next unless version == "v1" && signature
    return JSON.parse(raw_body) if secure_compare(signature, expected)
  end
  raise "No matching signature"
end

# Constant-time string comparison.
def secure_compare(a, b)
  return false unless a.bytesize == b.bytesize
  result = 0
  a.bytes.zip(b.bytes) { |x, y| result |= x ^ y }
  result.zero?
end

package webhooks

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/base64"
    "errors"
    "net/http"
    "strconv"
    "strings"
    "time"
)

const toleranceSeconds = 5 * 60

// rawBody: the request body bytes, read before any JSON decoding.
func VerifyWebhook(rawBody []byte, header http.Header, secret string) error {
    id := header.Get("webhook-id")
    timestamp := header.Get("webhook-timestamp")
    signatures := header.Get("webhook-signature")
    if id == "" || timestamp == "" || signatures == "" {
        return errors.New("missing webhook headers")
    }

    ts, err := strconv.ParseInt(timestamp, 10, 64)
    if err != nil {
        return errors.New("invalid timestamp")
    }
    if diff := time.Now().Unix() - ts; diff > toleranceSeconds || diff < -toleranceSeconds {
        return errors.New("timestamp outside the tolerance")
    }

    key, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(secret, "whsec_"))
    if err != nil {
        return errors.New("invalid secret")
    }
    mac := hmac.New(sha256.New, key)
    mac.Write([]byte(id + "." + timestamp + "."))
    mac.Write(rawBody)
    expected := mac.Sum(nil)

    for _, entry := range strings.Split(signatures, " ") {
        version, signature, found := strings.Cut(entry, ",")
        if !found || version != "v1" {
            continue
        }
        given, err := base64.StdEncoding.DecodeString(signature)
        if err == nil && hmac.Equal(given, expected) {
            return nil
        }
    }
    return errors.New("no matching signature")
}

using System;
using System.Security.Cryptography;
using System.Text;

public static class WebhookVerifier
{
    private const long ToleranceSeconds = 5 * 60;

    // rawBody: the request body bytes, read before any JSON deserialisation.
    public static void Verify(byte[] rawBody, string id, string timestamp, string signatures, string secret)
    {
        if (string.IsNullOrEmpty(id) || string.IsNullOrEmpty(timestamp) || string.IsNullOrEmpty(signatures))
            throw new UnauthorizedAccessException("Missing webhook headers");

        if (!long.TryParse(timestamp, out var ts) ||
            Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - ts) > ToleranceSeconds)
            throw new UnauthorizedAccessException("Timestamp outside the tolerance");

        var key = Convert.FromBase64String(secret.StartsWith("whsec_") ? secret[6..] : secret);
        var prefix = Encoding.UTF8.GetBytes($"{id}.{timestamp}.");
        var signed = new byte[prefix.Length + rawBody.Length];
        Buffer.BlockCopy(prefix, 0, signed, 0, prefix.Length);
        Buffer.BlockCopy(rawBody, 0, signed, prefix.Length, rawBody.Length);

        using var hmac = new HMACSHA256(key);
        var expected = hmac.ComputeHash(signed);

        foreach (var entry in signatures.Split(' ', StringSplitOptions.RemoveEmptyEntries))
        {
            var parts = entry.Split(',', 2);
            if (parts.Length != 2 || parts[0] != "v1") continue;
            byte[] given;
            try { given = Convert.FromBase64String(parts[1]); } catch (FormatException) { continue; }
            if (CryptographicOperations.FixedTimeEquals(given, expected)) return;
        }
        throw new UnauthorizedAccessException("No matching signature");
    }
}