Webhooks and sandbox

import base64
import hashlib
import hmac
import os
import time

from flask import Flask, request

# Your secret, format whsec_<base64>, >= 24 bytes. From your secret manager, never the repo.
WEBHOOK_SECRET = os.environ["PMX_WEBHOOK_SECRET"]
# Your own replay window. We publish no number; "too old" is unquantified on our side.
MAX_SKEW_SECONDS = 300

app = Flask(__name__)
seen_event_ids = set()  # in production this is your database, not memory

def signing_key(secret: str) -> bytes:
    # Standard Webhooks: the key is the base64-decoded bytes after the whsec_ prefix.
    return base64.b64decode(secret.removeprefix("whsec_"))

def verify(raw_body: bytes, webhook_id: str, webhook_timestamp: str, header_sig: str) -> bool:
    if abs(time.time() - int(webhook_timestamp)) > MAX_SKEW_SECONDS:
        return False
    signed = f"{webhook_id}.{webhook_timestamp}.".encode() + raw_body
    expected = base64.b64encode(
        hmac.new(signing_key(WEBHOOK_SECRET), signed, hashlib.sha256).digest()
    ).decode()
    # The header carries a space-separated list of "v<version>,<signature>".
    for part in header_sig.split(" "):
        _, _, candidate = part.partition(",")
        if candidate and hmac.compare_digest(candidate, expected):
            return True
    return False

@app.post("/pmx/kyc")
def receive():
    raw = request.get_data()  # raw bytes, before any parsing
    ok = verify(
        raw,
        request.headers.get("webhook-id", ""),
        request.headers.get("webhook-timestamp", "0"),
        request.headers.get("webhook-signature", ""),
    )
    if not ok:
        return "", 401

    event = request.get_json()
    event_id = event["event_id"]
    if event_id in seen_event_ids:
        return "", 200  # at-least-once delivery: dedupe and acknowledge
    seen_event_ids.add(event_id)

    enqueue(event)   # hand off; nothing slow runs before the acknowledgement
    return "", 200

def enqueue(event):
    print("queued", event["event_id"], event.get("type"))

import { createHmac, timingSafeEqual } from "node:crypto";
import express from "express";

// Your secret, format whsec_<base64>, >= 24 bytes. From your secret manager, never the repo.
const WEBHOOK_SECRET = process.env.PMX_WEBHOOK_SECRET!;
// Your own replay window. We publish no number; "too old" is unquantified on our side.
const MAX_SKEW_SECONDS = 300;

const seenEventIds = new Set<string>(); // in production this is your database

// Standard Webhooks: the key is the base64-decoded bytes after the whsec_ prefix.
const signingKey = Buffer.from(WEBHOOK_SECRET.replace(/^whsec_/, ""), "base64");

function verify(raw: Buffer, id: string, ts: string, headerSig: string): boolean {
  if (Math.abs(Date.now() / 1000 - Number(ts)) > MAX_SKEW_SECONDS) return false;
  const signed = Buffer.concat([Buffer.from(`${id}.${ts}.`), raw]);
  const expected = createHmac("sha256", signingKey).update(signed).digest("base64");
  // The header carries a space-separated list of "v<version>,<signature>".
  return headerSig.split(" ").some((part) => {
    const candidate = part.slice(part.indexOf(",") + 1);
    const a = Buffer.from(candidate);
    const b = Buffer.from(expected);
    return a.length === b.length && timingSafeEqual(a, b);
  });
}

const app = express();
// Raw bytes, before any parsing. express.json() would change the bytes and break every signature.
app.post("/pmx/kyc", express.raw({ type: "*/*" }), (req, res) => {
  const ok = verify(
    req.body as Buffer,
    String(req.header("webhook-id") ?? ""),
    String(req.header("webhook-timestamp") ?? "0"),
    String(req.header("webhook-signature") ?? ""),
  );
  if (!ok) return res.sendStatus(401);

  const event = JSON.parse((req.body as Buffer).toString("utf8"));
  if (seenEventIds.has(event.event_id)) return res.sendStatus(200); // dedupe, then acknowledge
  seenEventIds.add(event.event_id);

  console.log("queued", event.event_id, event.type); // do the work asynchronously
  return res.sendStatus(200);
});

app.listen(8080);

package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/base64"
	"encoding/json"
	"io"
	"math"
	"net/http"
	"os"
	"strconv"
	"strings"
	"sync"
	"time"
)

// Your secret, format whsec_<base64>, >= 24 bytes. From your secret manager, never the repo.
var webhookSecret = os.Getenv("PMX_WEBHOOK_SECRET")

// Your own replay window. We publish no number; "too old" is unquantified on our side.
const maxSkewSeconds = 300.0

var (
	mu   sync.Mutex
	seen = map[string]bool{} // in production this is your database
)

func signingKey() []byte {
	// Standard Webhooks: the key is the base64-decoded bytes after the whsec_ prefix.
	key, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(webhookSecret, "whsec_"))
	if err != nil {
		panic(err)
	}
	return key
}

func verify(raw []byte, id, ts, headerSig string) bool {
	sent, err := strconv.ParseFloat(ts, 64)
	if err != nil || math.Abs(float64(time.Now().Unix())-sent) > maxSkewSeconds {
		return false
	}
	mac := hmac.New(sha256.New, signingKey())
	mac.Write([]byte(id + "." + ts + "."))
	mac.Write(raw)
	expected := base64.StdEncoding.EncodeToString(mac.Sum(nil))
	// The header carries a space-separated list of "v<version>,<signature>".
	for _, part := range strings.Split(headerSig, " ") {
		if _, candidate, found := strings.Cut(part, ","); found {
			if hmac.Equal([]byte(candidate), []byte(expected)) {
				return true
			}
		}
	}
	return false
}

func main() {
	http.HandleFunc("/pmx/kyc", func(w http.ResponseWriter, r *http.Request) {
		raw, err := io.ReadAll(r.Body) // raw bytes, before any parsing
		if err != nil {
			w.WriteHeader(http.StatusBadRequest)
			return
		}
		if !verify(raw, r.Header.Get("webhook-id"), r.Header.Get("webhook-timestamp"), r.Header.Get("webhook-signature")) {
			w.WriteHeader(http.StatusUnauthorized)
			return
		}

		var event struct {
			EventID string `json:"event_id"`
			Type    string `json:"type"`
		}
		if err := json.Unmarshal(raw, &event); err != nil {
			w.WriteHeader(http.StatusBadRequest)
			return
		}

		mu.Lock()
		duplicate := seen[event.EventID]
		seen[event.EventID] = true
		mu.Unlock()
		if !duplicate {
			// Hand off; nothing slow runs before the acknowledgement.
			go func() { println("queued", event.EventID, event.Type) }()
		}
		w.WriteHeader(http.StatusOK) // acknowledge duplicates too
	})
	http.ListenAndServe(":8080", nil)
}

set -euo pipefail

# Test your own verifier end to end, offline, before you register anything.
# Your secret, format whsec_<base64>, >= 24 bytes.
SECRET="${PMX_WEBHOOK_SECRET}"
RECEIVER="http://localhost:8080/pmx/kyc"   # your endpoint

WEBHOOK_ID="msg_local_test_0001"
WEBHOOK_TIMESTAMP="$(date +%s)"
BODY='{"event_id":"evt_local_test_0001","type":"webhook.test"}'

# The signed content is exactly "<webhook-id>.<webhook-timestamp>.<raw body>".
KEY_HEX="$(printf '%s' "${SECRET#whsec_}" | base64 -d | xxd -p | tr -d '\n')"
SIG="$(printf '%s.%s.%s' "${WEBHOOK_ID}" "${WEBHOOK_TIMESTAMP}" "${BODY}" \
  | openssl dgst -sha256 -mac HMAC -macopt "hexkey:${KEY_HEX}" -binary \
  | base64)"

HTTP="$(curl -sS -o /tmp/receiver-resp.txt -w '%{http_code}' \
  -X POST "${RECEIVER}" \
  -H "Content-Type: application/json" \
  -H "webhook-id: ${WEBHOOK_ID}" \
  -H "webhook-timestamp: ${WEBHOOK_TIMESTAMP}" \
  -H "webhook-signature: v1,${SIG}" \
  --data-binary "${BODY}")"

[ "${HTTP}" = "200" ] || { echo "receiver returned HTTP ${HTTP}"; cat /tmp/receiver-resp.txt; exit 1; }

# Now prove it rejects a bad signature. A verifier that accepts this is not a verifier.
HTTP="$(curl -sS -o /dev/null -w '%{http_code}' \
  -X POST "${RECEIVER}" \
  -H "Content-Type: application/json" \
  -H "webhook-id: ${WEBHOOK_ID}" \
  -H "webhook-timestamp: ${WEBHOOK_TIMESTAMP}" \
  -H "webhook-signature: v1,AAAA" \
  --data-binary "${BODY}")"

[ "${HTTP}" = "401" ] || { echo "verifier accepted a bad signature (HTTP ${HTTP})"; exit 1; }
echo "verifier ok"