A documented REST API and signed webhooks

$ curl https://api.hobbstack.com/api/v1/external/aircraft
{"detail":"Bearer token required","code":"UNAUTHORIZED"}

$ curl -H "Authorization: Bearer hbs_pk_revoked_or_unknown_key_value_here" \
    https://api.hobbstack.com/api/v1/external/aircraft
{"detail":"Invalid or revoked API key","code":"UNAUTHORIZED"}

POST /your-endpoint HTTP/1.1
Content-Type: application/json
X-Hobbstack-Event: squawk.created
X-Hobbstack-Signature: sha256=6f1b...c92a
User-Agent: Hobbstack-Webhooks/1.0

{
  "event": "squawk.created",
  "delivered_at": "2026-08-04T18:22:11.204871+00:00",
  "data": {
    "id": "9c8b7a65-4321-4fed-8cba-0987654321fe",
    "aircraft_id": "b1c2d3e4-f5a6-4718-8293-a1b2c3d4e5f6",
    "description": "Left main tire worn to cord on outboard shoulder",
    "severity": "grounding",
    "is_grounding": true,
    "reported_by": "11111111-2222-4333-8444-555555555555",
    "created_at": "2026-08-04T18:22:10+00:00"
  }
}

import hashlib
import hmac
import os

from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["HOBBSTACK_WEBHOOK_SECRET"]  # shown once, at creation


@app.post("/hobbstack-webhook")
def receive():
    # Sign the RAW bytes. Hashing json.dumps(request.json) will not match:
    # key order and separators differ from what we sent.
    expected = "sha256=" + hmac.new(
        SECRET.encode(), request.get_data(), hashlib.sha256
    ).hexdigest()
    sent = request.headers.get("X-Hobbstack-Signature", "")

    # Compare BYTES. compare_digest() raises TypeError on str operands that
    # are not both ASCII-only, and Flask decodes header values as latin-1 —
    # so a hostile header carrying any byte >= 0x80 would turn a 401 into an
    # unhandled 500. errors="replace" keeps the encode itself total.
    if not hmac.compare_digest(sent.encode("utf-8", "replace"), expected.encode()):
        abort(401)

    envelope = request.get_json()
    event = envelope["event"]            # also in the X-Hobbstack-Event header
    data = envelope["data"]

    handle(event, data)

    # Answer 2xx quickly. Anything else counts as a failed attempt, and
    # five consecutive failures disable the subscription.
    return "", 200

import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.HOBBSTACK_WEBHOOK_SECRET; // shown once, at creation

// express.raw keeps req.body as a Buffer. express.json would give you a
// parsed object, and re-serialising it produces different bytes than the
// ones we signed, so every delivery would fail verification.
app.post(
  "/hobbstack-webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const expected =
      "sha256=" +
      crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
    const sent = req.get("X-Hobbstack-Signature") ?? "";

    const a = Buffer.from(sent);
    const b = Buffer.from(expected);
    // timingSafeEqual throws on a length mismatch, so check length first.
    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
      return res.sendStatus(401);
    }

    const envelope = JSON.parse(req.body.toString("utf8"));
    handle(envelope.event, envelope.data);

    // Answer 2xx quickly. Anything else counts as a failed attempt, and
    // five consecutive failures disable the subscription.
    res.sendStatus(200);
  },
);