Webhooks quickstart

// npm install express
import express from "express"
import { createPublicKey, verify } from "node:crypto"

// The endpoint's publicKey (whpk_...), which you get in step 3.
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",
})
const seen = new Set() // use a database table in production
const app = express()

function isGenuine(headers, rawBody) {
  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(`${headers["webhook-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")))
}

// express.raw keeps the body exactly as sent, which the signature check needs.
app.post("/webhooks/flow-payroll", express.raw({ type: "application/json" }), (req, res) => {
  if (!isGenuine(req.headers, req.body)) return res.status(400).send("Invalid signature")

  const event = JSON.parse(req.body)
  if (!seen.has(event.id)) {
    seen.add(event.id)
    console.log("Received", event.type, "for organisation", event.organisationId)
  }
  res.sendStatus(204)
})

app.listen(3000)

# pip install flask cryptography
import base64
import json
import os
import time

from cryptography.exceptions import InvalidSignature
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
from flask import Flask, request

# The endpoint's publicKey (whpk_...), which you get in step 3.
public_key = Ed25519PublicKey.from_public_bytes(
    base64.b64decode(os.environ["FLOW_WEBHOOK_PUBLIC_KEY"].removeprefix("whpk_"))
)
seen = set()  # use a database table in production
app = Flask(__name__)


def is_genuine(headers, raw_body):
    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


@app.post("/webhooks/flow-payroll")
def receive():
    raw_body = request.get_data()
    if not is_genuine(request.headers, raw_body):
        return "Invalid signature", 400

    event = json.loads(raw_body)
    if event["id"] not in seen:
        seen.add(event["id"])
        print("Received", event["type"], "for organisation", event["organisationId"])
    return "", 204


app.run(port=3000)

<?php
// Save as receiver.php and run: php -S 0.0.0.0:3000 receiver.php
// No package needed: sodium is bundled with PHP 7.2 and later.

function is_genuine(array $headers, string $rawBody): bool
{
    $timestamp = $headers['webhook-timestamp'] ?? '';
    if (!ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300) return false;

    // The endpoint's publicKey (whpk_...), which you get in step 3.
    $publicKey = base64_decode(substr(getenv('FLOW_WEBHOOK_PUBLIC_KEY'), strlen('whpk_')), true);
    if ($publicKey === false || strlen($publicKey) !== SODIUM_CRYPTO_SIGN_PUBLICKEYBYTES) return false;

    $message = ($headers['webhook-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;
}

// php://input is the body exactly as sent, which the signature check needs.
$rawBody = file_get_contents('php://input');
if (!is_genuine(array_change_key_case(getallheaders(), CASE_LOWER), $rawBody)) {
    http_response_code(400);
    exit('Invalid signature');
}

$event = json_decode($rawBody, true);
$seenFile = __DIR__ . '/seen-events.txt'; // use a database table in production
$seen = is_file($seenFile) ? file($seenFile, FILE_IGNORE_NEW_LINES) : [];
if (!in_array($event['id'], $seen, true)) {
    file_put_contents($seenFile, $event['id'] . PHP_EOL, FILE_APPEND | LOCK_EX);
    error_log("Received {$event['type']} for organisation {$event['organisationId']}");
}
http_response_code(204);