Webhooks

curl -s -X POST 'https://passkey-x.com/api/org/v1/webhooks' \
  -H "Authorization: Bearer $PASSKEY_X_API_KEY" -H 'Content-Type: application/json' \
  -d '{"name":"Contracts","url":"https://contracts.example.com/passkey-x","events":["document.signed","document.declined","document.sealed"]}'
# → the secret (pxwh_…) is shown once: store it

{
  "source": "passkey-x",
  "type": "audit_events",
  "webhook_id": "f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4a5b",
  "tenant_id": "8b6a3f1e-2c4d-4e5f-9a0b-1c2d3e4f5a6b",
  "sent_at": "2026-10-26T09:30:02Z",
  "first_sequence": 18341,
  "last_sequence": 18342,
  "events": [
    { "sequence": 18342, "occurred_at": "2026-10-26T09:30:00Z", "action": "remote.session_ended",
      "target_type": "remote_sessions", "target_id": "5a6b7c8d-9e0f-4a1b-8c3d-4e5f6a7b8c9d",
      "actor_identity_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9", "metadata": { "seconds": 412, "people": 2 },
      "hash_version": 2, "event_hash": "9a7f…" }
  ]
}

# Recompute the signature of a saved delivery (body.json = the raw body, byte for byte)
TS='1792540800'                       # X-PasskeyX-Timestamp
SIG='v1=5257a8…'                      # X-PasskeyX-Signature (may hold two: v1=<new>,v1=<old>)
EXPECTED="v1=$({ printf '%s.' "$TS"; cat body.json; } | openssl dgst -sha256 -hmac "$PX_WEBHOOK_SECRET" | awk '{print $NF}')"
case ",$SIG," in *",$EXPECTED,"*) echo "valid" ;; *) echo "INVALID" ;; esac

# Send yourself a signed test delivery
curl -s -X POST 'https://passkey-x.com/api/org/v1/webhooks/$WEBHOOK_ID/test' -H "Authorization: Bearer $PASSKEY_X_API_KEY"

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

/** true when any v1= signature matches one of your secrets (two during a rotation). */
export function verifyPasskeyX(rawBody, headers, secrets, toleranceSeconds = 300) {
  const timestamp = headers["x-passkeyx-timestamp"];
  if (!timestamp || Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSeconds) return false;
  const offered = String(headers["x-passkeyx-signature"] ?? "").split(",")
    .map((part) => part.trim()).filter((part) => part.startsWith("v1=")).map((part) => Buffer.from(part.slice(3), "hex"));
  return [secrets].flat().some((secret) => {
    const expected = createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest();
    return offered.some((signature) => signature.length === expected.length && timingSafeEqual(signature, expected));
  });
}

// Express: keep the raw body for verification
app.post("/passkey-x", express.raw({ type: "application/json" }), (req, res) => {
  if (!verifyPasskeyX(req.body.toString("utf8"), req.headers, [process.env.PX_SECRET, process.env.PX_SECRET_OLD].filter(Boolean))) return res.sendStatus(401);
  const delivery = JSON.parse(req.body);           // deduplicate on events[].sequence
  res.sendStatus(204);
});

import hashlib, hmac, time

def verify_passkey_x(raw_body: bytes, headers: dict, secrets: list[str], tolerance: int = 300) -> bool:
    timestamp = headers.get("X-PasskeyX-Timestamp", "")
    if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > tolerance:
        return False
    offered = [part.strip()[3:] for part in headers.get("X-PasskeyX-Signature", "").split(",") if part.strip().startswith("v1=")]
    signed = timestamp.encode() + b"." + raw_body
    for secret in secrets:  # the new and, during a rotation, the old secret
        expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
        if any(hmac.compare_digest(expected, candidate) for candidate in offered):
            return True
    return False

# Flask
@app.post("/passkey-x")
def passkey_x():
    if not verify_passkey_x(request.get_data(), request.headers, [os.environ["PX_SECRET"]]):
        abort(401)
    delivery = request.get_json()  # deduplicate on events[].sequence
    return "", 204

import { verifyWebhook } from "@passkey-x/sdk/webhooks";
// While a secret rotates, deliveries carry v1=<new>,v1=<old>: keep both secrets until the overlap ends.

// Next.js route handler (app/api/passkey-x/route.ts); the same works in Express, Workers or Deno.
export async function POST(request: Request) {
  const body = await request.text(); // verify the RAW body before parsing it
  try {
    await verifyWebhook({ body, headers: request.headers, secrets: [process.env.PX_WEBHOOK_SECRET!, process.env.PX_WEBHOOK_SECRET_OLD].filter(Boolean) as string[] });
  } catch {
    return new Response("invalid signature", { status: 401 });
  }
  const { events } = JSON.parse(body); // at-least-once and in order: deduplicate on event.sequence
  return new Response(null, { status: 204 });
}

curl -s -X POST "https://passkey-x.com/api/org/v1/webhooks/$WEBHOOK_ID/rotate-secret" \
  -H "Authorization: Bearer $PASSKEY_X_API_KEY" -H 'Content-Type: application/json' \
  -d '{ "overlap_hours": 24 }'
# Until the overlap ends, deliveries carry X-PasskeyX-Signature: v1=<new>,v1=<old>