Partner API webhooks: events, signing and retries

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

const SECRET = process.env.HD_WEBHOOK_SECRET; // whsec_...
const TOLERANCE_SECONDS = 300;
const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;

function signingKey(secret) {
  if (typeof secret !== "string" || !secret.startsWith("whsec_")) return null;
  const encoded = secret.slice("whsec_".length);
  // Strict standard base64: Buffer.from() alone would also accept url-safe or broken input.
  if (!BASE64.test(encoded)) return null;
  const key = Buffer.from(encoded, "base64");
  return key.length >= 24 && key.length <= 64 ? key : null;
}

export function verifyWebhook(rawBody, headers, secret = SECRET, now = Date.now() / 1000) {
  const lowered = {};
  for (const [name, value] of Object.entries(headers ?? {})) lowered[name.toLowerCase()] = value;
  const id = lowered["webhook-id"] ?? "";
  const timestamp = String(lowered["webhook-timestamp"] ?? "").trim();
  const signatures = [];
  for (const entry of String(lowered["webhook-signature"] ?? "").split(" ")) {
    const comma = entry.indexOf(",");
    if (comma !== -1 && entry.slice(0, comma) === "v1" && comma < entry.length - 1) {
      signatures.push(entry.slice(comma + 1));
    }
  }
  if (!id || !/^[0-9]+$/.test(timestamp) || signatures.length === 0) return false;
  // Whole seconds on both sides, like Hi Doctor: drop the fraction of the clock.
  const seconds = Number(timestamp);
  if (Math.abs(Math.trunc(now) - seconds) > TOLERANCE_SECONDS) return false;
  const key = signingKey(secret);
  if (key === null) return false;
  const expected = Buffer.from(
    createHmac("sha256", key).update(`${id}.${seconds}.`).update(rawBody).digest("base64"),
  );
  return signatures.some((signature) => {
    const candidate = Buffer.from(signature);
    return candidate.length === expected.length && timingSafeEqual(candidate, expected);
  });
}

const app = express();
app.post("/hi-doctor/webhooks", express.raw({ type: "application/json" }), (req, res) => {
  if (!verifyWebhook(req.body, req.headers)) {
    return res.status(400).send("invalid signature");
  }
  const event = JSON.parse(req.body.toString("utf8"));
  // Store the event keyed by req.get("webhook-id"), then answer quickly.
  res.status(200).send("ok");
});
app.listen(3000);

import base64
import binascii
import hashlib
import hmac
import json
import os
import time

from flask import Flask, abort, request

SECRET = os.environ["HD_WEBHOOK_SECRET"]  # whsec_...
TOLERANCE_SECONDS = 300


def signing_key(secret: str) -> bytes | None:
    if not isinstance(secret, str) or not secret.startswith("whsec_"):
        return None
    try:
        # validate=True: strict standard base64, no url-safe characters or whitespace.
        key = base64.b64decode(secret[len("whsec_"):], validate=True)
    except (binascii.Error, ValueError):
        return None
    return key if 24 <= len(key) <= 64 else None


def verify_webhook(raw_body: bytes, headers, secret: str = SECRET, now: float | None = None) -> bool:
    lowered = {str(name).lower(): value for name, value in (headers or {}).items()}
    msg_id = lowered.get("webhook-id") or ""
    timestamp = (lowered.get("webhook-timestamp") or "").strip()
    signatures = []
    for entry in (lowered.get("webhook-signature") or "").split(" "):
        version, _, signature = entry.partition(",")
        if version == "v1" and signature:
            signatures.append(signature)
    if not msg_id or not (timestamp.isascii() and timestamp.isdigit()) or not signatures:
        return False
    seconds = int(timestamp)
    # Whole seconds on both sides, like Hi Doctor; an explicit now=0 is honoured.
    current = int(time.time() if now is None else now)
    if abs(current - seconds) > TOLERANCE_SECONDS:
        return False
    key = signing_key(secret)
    if key is None:
        return False
    digest = hmac.new(key, f"{msg_id}.{seconds}.".encode() + raw_body, hashlib.sha256).digest()
    expected = base64.b64encode(digest)
    return any(hmac.compare_digest(expected, signature.encode()) for signature in signatures)


app = Flask(__name__)


@app.post("/hi-doctor/webhooks")
def receive():
    raw_body = request.get_data()
    if not verify_webhook(raw_body, request.headers):
        abort(400)
    event = json.loads(raw_body)
    # Store the event keyed by request.headers["webhook-id"], then answer quickly.
    return "ok", 200

const seenEvents = new Set();
const consultations = new Map();

export function applyEvent(eventId, event) {
  if (seenEvents.has(eventId)) return "duplicate";
  seenEvents.add(eventId);
  if (event.type === "endpoint.test") return "test";
  const snapshot = event.data;
  const stored = consultations.get(snapshot.id);
  if (stored && stored.version >= event.version) return "stale";
  consultations.set(snapshot.id, { ...snapshot, version: event.version });
  return "applied";
}

seen_events: set[str] = set()
consultations: dict[str, dict] = {}


def apply_event(event_id: str, event: dict) -> str:
    if event_id in seen_events:
        return "duplicate"
    seen_events.add(event_id)
    if event["type"] == "endpoint.test":
        return "test"
    snapshot = event["data"]
    stored = consultations.get(snapshot["id"])
    if stored and stored["version"] >= event["version"]:
        return "stale"
    consultations[snapshot["id"]] = {**snapshot, "version": event["version"]}
    return "applied"