Verify signatures

// Built-in crypto, no package needed.
import { createPublicKey, verify } from "node:crypto"

// The endpoint's publicKey, for example whpk_jIEdhT6g5KvNSUn1KOiDuDQTX9V1cEhCxOh9pvUgTcc=
const publicKey = createPublicKey({
  key: {
    kty: "OKP",
    crv: "Ed25519",
    x: Buffer.from(process.env.FLOW_WEBHOOK_PUBLIC_KEY.slice("whpk_".length), "base64").toString("base64url"),
  },
  format: "jwk",
})

// rawBody is the request body as a Buffer, exactly as received.
export function isValid(headers, rawBody) {
  const id = headers["webhook-id"] ?? ""
  const timestamp = headers["webhook-timestamp"] ?? ""
  if (!/^\d+$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false

  const message = Buffer.concat([Buffer.from(`${id}.${timestamp}.`, "utf8"), rawBody])
  return (headers["webhook-signature"] ?? "")
    .split(" ")
    .filter((entry) => entry.startsWith("v1a,"))
    .some((entry) => verify(null, message, publicKey, Buffer.from(entry.slice("v1a,".length), "base64")))
}

# pip install cryptography
import base64
import os
import time

from cryptography.exceptions import InvalidSignature
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey

# The endpoint's publicKey, for example whpk_jIEdhT6g5KvNSUn1KOiDuDQTX9V1cEhCxOh9pvUgTcc=
public_key = Ed25519PublicKey.from_public_bytes(
    base64.b64decode(os.environ["FLOW_WEBHOOK_PUBLIC_KEY"].removeprefix("whpk_"))
)


def is_valid(headers, raw_body: bytes) -> bool:
    timestamp = headers.get("webhook-timestamp", "")
    if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > 300:
        return False

    message = f'{headers.get("webhook-id", "")}.{timestamp}.'.encode() + raw_body
    for entry in headers.get("webhook-signature", "").split(" "):
        version, _, signature = entry.partition(",")
        if version != "v1a":
            continue
        try:
            public_key.verify(base64.b64decode(signature), message)
            return True
        except (InvalidSignature, ValueError):
            continue
    return False

// dotnet add package BouncyCastle.Cryptography
using System.Text;
using Org.BouncyCastle.Crypto.Parameters;
using Org.BouncyCastle.Crypto.Signers;

public static class FlowWebhookPublicKey
{
    private static readonly TimeSpan Tolerance = TimeSpan.FromMinutes(5);

    /// <summary>True when the delivery carries a v1a signature from your endpoint's key, made in the last five minutes.</summary>
    public static bool IsValid(string publicKey, string id, string timestamp, string signatureHeader, byte[] rawBody)
    {
        if (!long.TryParse(timestamp, out var seconds)) return false;
        var age = DateTimeOffset.UtcNow - DateTimeOffset.FromUnixTimeSeconds(seconds);
        if (age.Duration() > Tolerance) return false;

        var key = new Ed25519PublicKeyParameters(Convert.FromBase64String(publicKey["whpk_".Length..]));
        var message = Encoding.UTF8.GetBytes($"{id}.{timestamp}.").Concat(rawBody).ToArray();

        foreach (var entry in signatureHeader.Split(' ', StringSplitOptions.RemoveEmptyEntries))
        {
            var parts = entry.Split(',', 2);
            if (parts.Length != 2 || parts[0] != "v1a") continue;
            byte[] signature;
            try
            {
                signature = Convert.FromBase64String(parts[1]);
            }
            catch (FormatException)
            {
                continue;
            }

            var verifier = new Ed25519Signer();
            verifier.Init(false, key);
            verifier.BlockUpdate(message, 0, message.Length);
            if (verifier.VerifySignature(signature)) return true;
        }
        return false;
    }
}

// In your handler, read the body as bytes before anything parses it:
// FlowWebhookPublicKey.IsValid(publicKey, Request.Headers["webhook-id"], Request.Headers["webhook-timestamp"],
//                              Request.Headers["webhook-signature"], rawBody)

<?php
// No package needed: sodium is bundled with PHP 7.2 and later.

// $headers uses lower-case names; $rawBody is the request body exactly as received.
function flow_webhook_public_key_is_valid(array $headers, string $rawBody): bool
{
    $id = $headers['webhook-id'] ?? '';
    $timestamp = $headers['webhook-timestamp'] ?? '';
    if (!ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300) return false;

    // The endpoint's publicKey, for example whpk_jIEdhT6g5KvNSUn1KOiDuDQTX9V1cEhCxOh9pvUgTcc=
    $publicKey = base64_decode(substr(getenv('FLOW_WEBHOOK_PUBLIC_KEY'), strlen('whpk_')), true);
    if ($publicKey === false || strlen($publicKey) !== SODIUM_CRYPTO_SIGN_PUBLICKEYBYTES) return false;

    $message = "{$id}.{$timestamp}." . $rawBody;
    foreach (explode(' ', $headers['webhook-signature'] ?? '') as $entry) {
        [$version, $signature] = array_pad(explode(',', $entry, 2), 2, '');
        if ($version !== 'v1a') continue;
        $signature = base64_decode($signature, true);
        if ($signature === false || strlen($signature) !== SODIUM_CRYPTO_SIGN_BYTES) continue;
        if (sodium_crypto_sign_verify_detached($signature, $message, $publicKey)) return true;
    }
    return false;
}

// In your handler, read the body before anything parses it:
// $headers = array_change_key_case(getallheaders(), CASE_LOWER);
// flow_webhook_public_key_is_valid($headers, file_get_contents('php://input'))

// npm install standardwebhooks
import express from "express"
import { Webhook } from "standardwebhooks"

const webhook = new Webhook(process.env.FLOW_WEBHOOK_SECRET)
const app = express()

app.post("/webhooks/flow-payroll", express.raw({ type: "application/json" }), (req, res) => {
  let event
  try {
    event = webhook.verify(req.body.toString("utf8"), req.headers)
  } catch {
    return res.status(400).send("Invalid signature")
  }
  res.sendStatus(204)
  queueForProcessing(event)
})

# pip install standardwebhooks
import os
from flask import Flask, request
from standardwebhooks.webhooks import Webhook

webhook = Webhook(os.environ["FLOW_WEBHOOK_SECRET"])
app = Flask(__name__)

@app.post("/webhooks/flow-payroll")
def receive():
    try:
        event = webhook.verify(request.get_data(as_text=True), dict(request.headers))
    except Exception:
        return "Invalid signature", 400
    queue_for_processing(event)
    return "", 204

// No package needed.
using System.Security.Cryptography;
using System.Text;

public static class FlowWebhook
{
    private static readonly TimeSpan Tolerance = TimeSpan.FromMinutes(5);

    /// <summary>True when the delivery was signed with your secret in the last five minutes.</summary>
    public static bool IsValid(string secret, string id, string timestamp, string signatureHeader, byte[] rawBody)
    {
        if (!long.TryParse(timestamp, out var seconds)) return false;
        var age = DateTimeOffset.UtcNow - DateTimeOffset.FromUnixTimeSeconds(seconds);
        if (age.Duration() > Tolerance) return false;

        var key = Convert.FromBase64String(secret.StartsWith("whsec_") ? secret["whsec_".Length..] : secret);
        var expected = HMACSHA256.HashData(key, Encoding.UTF8.GetBytes($"{id}.{timestamp}.").Concat(rawBody).ToArray());

        foreach (var entry in signatureHeader.Split(' ', StringSplitOptions.RemoveEmptyEntries))
        {
            var parts = entry.Split(',', 2);
            if (parts.Length != 2 || parts[0] != "v1") continue;
            try
            {
                if (CryptographicOperations.FixedTimeEquals(Convert.FromBase64String(parts[1]), expected)) return true;
            }
            catch (FormatException)
            {
            }
        }
        return false;
    }
}

// In your handler, read the body as bytes before anything parses it:
// FlowWebhook.IsValid(secret, Request.Headers["webhook-id"], Request.Headers["webhook-timestamp"],
//                     Request.Headers["webhook-signature"], rawBody)

<?php
// No package needed.

// $headers uses lower-case names; $rawBody is the request body exactly as received.
function flow_webhook_is_valid(array $headers, string $rawBody): bool
{
    $id = $headers['webhook-id'] ?? '';
    $timestamp = $headers['webhook-timestamp'] ?? '';
    if (!ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300) return false;

    $key = base64_decode(preg_replace('/^whsec_/', '', getenv('FLOW_WEBHOOK_SECRET')), true);
    if ($key === false) return false;
    $expected = hash_hmac('sha256', "{$id}.{$timestamp}." . $rawBody, $key, true);

    foreach (explode(' ', $headers['webhook-signature'] ?? '') as $entry) {
        [$version, $signature] = array_pad(explode(',', $entry, 2), 2, '');
        if ($version !== 'v1') continue;
        $signature = base64_decode($signature, true);
        if ($signature !== false && hash_equals($expected, $signature)) return true;
    }
    return false;
}

// In your handler, read the body before anything parses it:
// $headers = array_change_key_case(getallheaders(), CASE_LOWER);
// flow_webhook_is_valid($headers, file_get_contents('php://input'))