import type { ApiConfig } from "@getspot/spot-widget";

// Point the widget at an environment and partner. Set these in .env.local; the
// widget resolves `environment` to the right Spot API base URL on its own.
// Setting VITE_SPOT_CUSTOM_ENDPOINT overrides that resolution entirely; leave it
// unset for Sandbox and production.
export const apiConfig: ApiConfig = {
  environment: (import.meta.env.VITE_SPOT_ENV ?? "sandbox") as ApiConfig["environment"],
  partnerId: import.meta.env.VITE_SPOT_PARTNER_ID ?? "",
  ...(import.meta.env.VITE_SPOT_CUSTOM_ENDPOINT
    ? { customEndpoint: import.meta.env.VITE_SPOT_CUSTOM_ENDPOINT }
    : {}),
};

import type { QuoteItem } from "@getspot/spot-widget";

function isoDaysFromNow(days: number): string {
  const millisecondsPerDay = 24 * 60 * 60 * 1000;
  return new Date(Date.now() + days * millisecondsPerDay).toISOString();
}

/**
 * A starting quote request so the widget renders a real quote out of the box.
 * Offer matching is driven mainly by productId together with productType and
 * productDuration, so replace these defaults with the values provisioned for
 * your partner account, or tweak them at runtime in the booking form. A real
 * integration builds this object from its own cart data.
 */
export function buildDefaultQuoteRequest(): QuoteItem {
  return {
    productPrice: 500,
    productType: "Pass",
    productDuration: "Seasonal",
    productId: "example-pass-001",
    productName: "Season Pass",
    cartId: "example-cart",
    cartName: "Sample Cart",
    eventType: "Travel Experience",
    currencyCode: "USD",
    // A short window keeps the request under offers that cap coverage duration.
    startDate: isoDaysFromNow(7),
    endDate: isoDaysFromNow(9),
    hostCountry: "US",
    hostCountryState: "TX",
    destinations: ["US"],
    isPartialPayment: false,
  };
}

import type { RefObject } from "react";
import ReactSpotWidget, {
  type ReactSpotWidgetRef,
} from "@getspot/spot-widget-react";
import type { ApiConfig, Quote, QuoteItem, SelectionData } from "@getspot/spot-widget";

interface WidgetPanelProps {
  widgetRef: RefObject<ReactSpotWidgetRef>;
  apiConfig: ApiConfig;
  quoteRequestData: QuoteItem;
  onQuoteRetrieved: (quote: Quote) => void;
  onOptIn: (data: SelectionData) => void;
  onOptOut: (data: SelectionData) => void;
  onError: (error: { message: string; status?: number }) => void;
  onNoMatchingQuote: (data: { status: string; data: unknown }) => void;
}

/**
 * Hosts the Spot widget. Its only job here is to request and render a quote;
 * capturing the customer's selection at checkout comes in the next step.
 */
export function WidgetPanel({
  widgetRef,
  apiConfig,
  quoteRequestData,
  onQuoteRetrieved,
  onOptIn,
  onOptOut,
  onError,
  onNoMatchingQuote,
}: WidgetPanelProps) {
  return (
    <section className="panel">
      <div className="panel__header">
        <h2>Widget</h2>
      </div>
      <div className="widget-host">
        <ReactSpotWidget
          ref={widgetRef}
          apiConfig={apiConfig}
          quoteRequestData={quoteRequestData}
          showTable={false}
          onQuoteRetrieved={onQuoteRetrieved}
          onOptIn={onOptIn}
          onOptOut={onOptOut}
          onError={onError}
          onNoMatchingQuote={onNoMatchingQuote}
        />
      </div>
    </section>
  );
}

@@ -1,19 +1,32 @@
-import { useState } from "react";
-import { buildDefaultQuoteRequest, type QuoteItem, type Purchaser } from "./types";
+import { useRef, useState } from "react";
+import type { ReactSpotWidgetRef } from "@getspot/spot-widget-react";
+import type { QuoteItem } from "@getspot/spot-widget";
+import { apiConfig } from "./config";
+import { buildDefaultQuoteRequest } from "./defaultQuote";
 import { QuoteForm } from "./components/QuoteForm";
+import { WidgetPanel } from "./components/WidgetPanel";
 import { PurchaserForm } from "./components/PurchaserForm";
+import type { Purchaser } from "./types";
 
 export function App() {
-  const [booking, setBooking] = useState<QuoteItem>(buildDefaultQuoteRequest);
+  // Hold the initial quote request stable so editing the form never remounts
+  // the widget (which would lose the selection); re-quote via updateQuote().
+  const initialQuoteRef = useRef<QuoteItem>(buildDefaultQuoteRequest());
+  const widgetRef = useRef<ReactSpotWidgetRef>(null);
+
+  const [draft, setDraft] = useState<QuoteItem>(initialQuoteRef.current);
+  const [applied, setApplied] = useState<QuoteItem>(initialQuoteRef.current);
   const [purchaser, setPurchaser] = useState<Purchaser>({
     firstName: "Test",
     lastName: "Purchaser",
     email: "[email protected]",
   });
-  const [placed, setPlaced] = useState(false);
 
-  function handleCheckout() {
-    setPlaced(true);
+  const dirty = JSON.stringify(draft) !== JSON.stringify(applied);
+
+  async function handleApply() {
+    setApplied(draft);
+    await widgetRef.current?.updateQuote(draft);
   }
 
   return (
@@ -22,38 +35,32 @@ export function App() {
         <div>
           <h1>Spot widget example</h1>
           <p className="muted">
-            A sample partner checkout. This is the starting point, before the
-            Spot widget is added.
+            A sample partner integration consuming{" "}
+            <code>@getspot/spot-widget-react</code>.
           </p>
         </div>
+        <div className="badges">
+          <span className="badge">env: {apiConfig.environment}</span>
+        </div>
       </header>
 
       <main className="app__grid">
         <div className="app__column">
-          <QuoteForm value={booking} onChange={setBooking} />
+          <QuoteForm value={draft} onChange={setDraft} onApply={handleApply} dirty={dirty} />
           <PurchaserForm value={purchaser} onChange={setPurchaser} />
         </div>
 
         <div className="app__column">
-          <section className="panel">
-            <div className="panel__header">
-              <h2>Checkout</h2>
-            </div>
-            <p className="muted">
-              Review the booking and place the order. The Spot widget will slot
-              in here in the next step of the guide.
-            </p>
-            <button type="button" className="button button--primary" onClick={handleCheckout}>
-              Proceed to checkout
-            </button>
-            {placed && (
-              <p className="notice notice--ok">
-                Order placed for {purchaser.firstName} {purchaser.lastName}:{" "}
-                {booking.productName} ({booking.currencyCode}{" "}
-                {booking.productPrice}).
-              </p>
-            )}
-          </section>
+          <WidgetPanel
+            widgetRef={widgetRef}
+            apiConfig={apiConfig}
+            quoteRequestData={initialQuoteRef.current}
+            onQuoteRetrieved={() => {}}
+            onOptIn={() => {}}
+            onOptOut={() => {}}
+            onError={() => {}}
+            onNoMatchingQuote={() => {}}
+          />
         </div>
       </main>
     </div>

@@ -1,8 +1,10 @@
-import type { QuoteItem } from "../types";
+import type { QuoteItem } from "@getspot/spot-widget";
 
 interface QuoteFormProps {
   value: QuoteItem;
   onChange: (next: QuoteItem) => void;
+  onApply: () => void;
+  dirty: boolean;
 }
 
 const PRODUCT_TYPES: QuoteItem["productType"][] = ["Trip", "Pass", "Registration"];
@@ -23,7 +25,7 @@ function fromDateInput(value: string): string {
 }
 
 /** Editable view of the fields a partner most commonly varies per booking. */
-export function QuoteForm({ value, onChange }: QuoteFormProps) {
+export function QuoteForm({ value, onChange, onApply, dirty }: QuoteFormProps) {
   function update<Key extends keyof QuoteItem>(key: Key, next: QuoteItem[Key]) {
     onChange({ ...value, [key]: next });
   }
@@ -181,6 +183,15 @@ export function QuoteForm({ value, onChange }: QuoteFormProps) {
           />
         </div>
       </div>
+
+      <button
+        type="button"
+        className="button button--primary"
+        onClick={onApply}
+        disabled={!dirty}
+      >
+        {dirty ? "Apply changes and re-quote" : "Quote is up to date"}
+      </button>
     </section>
   );
 }

@@ -1,6 +1,6 @@
 import { useRef, useState } from "react";
 import type { ReactSpotWidgetRef } from "@getspot/spot-widget-react";
-import type { QuoteItem } from "@getspot/spot-widget";
+import type { QuoteItem, SelectionData } from "@getspot/spot-widget";
 import { apiConfig } from "./config";
 import { buildDefaultQuoteRequest } from "./defaultQuote";
 import { QuoteForm } from "./components/QuoteForm";
@@ -21,6 +21,7 @@ export function App() {
     lastName: "Purchaser",
     email: "[email protected]",
   });
+  const [checkoutIntent, setCheckoutIntent] = useState<SelectionData | null>(null);
 
   const dirty = JSON.stringify(draft) !== JSON.stringify(applied);
 
@@ -29,6 +30,21 @@ export function App() {
     await widgetRef.current?.updateQuote(draft);
   }
 
+  /**
+   * Real checkouts are forms, so the widget is mounted inside one and the
+   * checkout button is a submit control. Enter in any field submits too,
+   * which is why every other button sets type="button".
+   */
+  async function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    if (!widgetRef.current?.validateSelection()) return;
+    await handleCheckout(widgetRef.current?.getSelection() ?? null);
+  }
+
+  function handleCheckout(selection: SelectionData | null) {
+    setCheckoutIntent(selection);
+  }
+
   return (
     <div className="app">
       <header className="app__header">
@@ -44,24 +60,39 @@ export function App() {
         </div>
       </header>
 
-      <main className="app__grid">
-        <div className="app__column">
-          <QuoteForm value={draft} onChange={setDraft} onApply={handleApply} dirty={dirty} />
-          <PurchaserForm value={purchaser} onChange={setPurchaser} />
-        </div>
+      <main>
+        <form className="app__grid" onSubmit={handleSubmit}>
+          <div className="app__column">
+            <QuoteForm value={draft} onChange={setDraft} onApply={handleApply} dirty={dirty} />
+            <PurchaserForm value={purchaser} onChange={setPurchaser} />
+          </div>
 
-        <div className="app__column">
-          <WidgetPanel
-            widgetRef={widgetRef}
-            apiConfig={apiConfig}
-            quoteRequestData={initialQuoteRef.current}
-            onQuoteRetrieved={() => {}}
-            onOptIn={() => {}}
-            onOptOut={() => {}}
-            onError={() => {}}
-            onNoMatchingQuote={() => {}}
-          />
-        </div>
+          <div className="app__column">
+            <WidgetPanel
+              widgetRef={widgetRef}
+              apiConfig={apiConfig}
+              quoteRequestData={initialQuoteRef.current}
+              onQuoteRetrieved={() => {}}
+              onOptIn={() => {}}
+              onOptOut={() => {}}
+              onError={() => {}}
+              onNoMatchingQuote={() => {}}
+            />
+
+            {checkoutIntent && (
+              <section className="panel panel--seam">
+                <div className="panel__header">
+                  <h2>Selection captured</h2>
+                </div>
+                <p className="muted">
+                  status <code>{checkoutIntent.status}</code>, quote{" "}
+                  <code>{checkoutIntent.quoteId ?? "(none)"}</code>. Next we send
+                  this to the backend.
+                </p>
+              </section>
+            )}
+          </div>
+        </form>
       </main>
     </div>
   );

import { config } from "../config.js";

interface CachedToken {
  accessToken: string;
  expiresAt: number;
}

let cachedToken: CachedToken | null = null;

// Refresh a bit before the real expiry so an in-flight request never uses a
// token that expires mid-call. The token lives 24h, so this margin is generous.
const EXPIRY_MARGIN_MS = 60_000;

/**
 * Client-credentials token, cached in memory. This is the whole reason a
 * partner needs a backend: the client secret is required to obtain this token
 * and must never reach the browser.
 */
async function getAccessToken(): Promise<string> {
  const now = Date.now();
  if (cachedToken && cachedToken.expiresAt - EXPIRY_MARGIN_MS > now) {
    return cachedToken.accessToken;
  }

  const response = await fetch(`${config.spotApiBase}/api/oauth/token`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      client_id: config.clientId,
      client_secret: config.clientSecret,
    }),
  });

  if (!response.ok) {
    const body = await response.text();
    throw new Error(`Token request failed (${response.status}): ${body}`);
  }

  const data = (await response.json()) as {
    access_token: string;
    expires_in: number;
  };
  cachedToken = {
    accessToken: data.access_token,
    expiresAt: now + data.expires_in * 1000,
  };
  return cachedToken.accessToken;
}

export interface SpotCallResult {
  status: number;
  body: unknown;
}

async function authedPost(path: string, payload: unknown): Promise<SpotCallResult> {
  const token = await getAccessToken();
  const response = await fetch(`${config.spotApiBase}${path}`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${token}`,
      "X-Spot-Partner-Id": config.partnerId,
    },
    body: JSON.stringify(payload),
  });

  const text = await response.text();
  let body: unknown = text;
  try {
    body = text ? JSON.parse(text) : null;
  } catch {
    // leave body as raw text if it is not JSON
  }
  return { status: response.status, body };
}

export function acceptQuote(quoteId: string, payload: unknown): Promise<SpotCallResult> {
  return authedPost(`/api/v1/quote/${encodeURIComponent(quoteId)}/accept`, payload);
}

// Spot's decline endpoint takes no request body.
export function declineQuote(quoteId: string): Promise<SpotCallResult> {
  return authedPost(`/api/v1/quote/${encodeURIComponent(quoteId)}/decline`, {});
}

@@ -1,6 +1,20 @@
 import "dotenv/config";
 
+function required(name: string): string {
+  const value = process.env[name];
+  if (!value) {
+    throw new Error(
+      `Missing required env var ${name}. Copy apps/server/.env.example to apps/server/.env and fill it in.`,
+    );
+  }
+  return value;
+}
+
 export const config = {
+  spotApiBase: process.env.SPOT_API_BASE ?? "https://api.sandbox.getspot.com",
+  partnerId: required("SPOT_PARTNER_ID"),
+  clientId: required("SPOT_CLIENT_ID"),
+  clientSecret: required("SPOT_CLIENT_SECRET"),
   port: Number(process.env.PORT ?? 8787),
   // Both sample frontends may call the backend: React (5180) and vanilla (5181).
   frontendOrigins: (

@@ -1,11 +1,80 @@
 import cors from "cors";
 import express from "express";
 import { config } from "./config.js";
+import { acceptQuote, declineQuote, type SpotCallResult } from "./spot/spotClient.js";
 
 const app = express();
 app.use(cors({ origin: config.frontendOrigins }));
 app.use(express.json());
 
+// ===========================================================================
+// The actual Spot integration. This is the code a partner writes.
+// ===========================================================================
+
+/**
+ * Accept a quote. This is what actually creates coverage, and it is why a
+ * backend exists: it attaches the OAuth bearer token the browser cannot hold.
+ */
+app.post("/accept", async (req, res) => {
+  const { quoteId, productPrice, purchaser, transactionId, transactionItemId } =
+    req.body ?? {};
+
+  if (!quoteId || typeof productPrice !== "number" || !purchaser) {
+    res.status(400).json({
+      error: "quoteId, productPrice (number), and purchaser are required",
+    });
+    return;
+  }
+
+  // Spot dedupes accept requests that reuse the same transactionItemId, so a
+  // retry cannot double-charge. The key below is derived from transactionId,
+  // so require a stable one rather than minting a fresh UUID per request.
+  if (!transactionId) {
+    res.status(400).json({
+      error: "transactionId is required and must be stable across retries of the same order",
+    });
+    return;
+  }
+  const payload = {
+    productPrice,
+    purchaser,
+    transactionId,
+    // One key per cart line; this sample has a single item.
+    transactionItemId: transactionItemId ?? `${transactionId}-1`,
+  };
+
+  await forward(res, () => acceptQuote(quoteId, payload));
+});
+
+/**
+ * Decline a quote. Always report declines as well as accepts so Spot keeps a
+ * complete, accurate record of every coverage decision.
+ */
+app.post("/decline", async (req, res) => {
+  const { quoteId } = req.body ?? {};
+  if (!quoteId) {
+    res.status(400).json({ error: "quoteId is required" });
+    return;
+  }
+  await forward(res, () => declineQuote(quoteId));
+});
+
+/** Run a Spot call and mirror its status and body back to the caller. */
+async function forward(
+  res: express.Response,
+  call: () => Promise<SpotCallResult>,
+): Promise<void> {
+  try {
+    const result = await call();
+    res.status(result.status).json(result.body);
+  } catch (error) {
+    // Network or token-exchange failure, not a Spot API rejection.
+    res.status(502).json({ error: (error as Error).message });
+  }
+}
+
 app.listen(config.port, () => {
-  console.log(`Spot example backend listening on http://localhost:${config.port}`);
+  console.log(
+    `Spot example backend listening on http://localhost:${config.port} -> ${config.spotApiBase}`,
+  );
 });

// BFF = "backend for frontend": a small backend that exists to serve this
// frontend. The browser cannot call Spot's accept/decline endpoints directly
// (they need an OAuth secret that must not ship to the browser), so it calls
// our own backend, which holds the secret and forwards to Spot. This module is
// the browser's client for that backend.

import { backendUrl } from "./config";

/** Buyer details collected at checkout and sent to the backend for the accept call. */
export interface Purchaser {
  firstName: string;
  lastName: string;
  email: string;
}

/** Normalized result of a backend call: whether it succeeded, the HTTP status
 *  (0 means the request never reached the backend), and the parsed body. */
export interface CheckoutResult {
  ok: boolean;
  status: number;
  body: unknown;
}

async function post(path: string, payload: unknown): Promise<CheckoutResult> {
  const response = await fetch(`${backendUrl}${path}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(payload),
  });
  let body: unknown = null;
  try {
    body = await response.json();
  } catch {
    // no-op: leave body null if the response was not JSON
  }
  return { ok: response.ok, status: response.status, body };
}

/**
 * Ask the backend to accept (bind) the quote. Creates coverage.
 * transactionId must stay stable across retries; the server derives the
 * idempotency key (transactionItemId) from it.
 */
export function acceptQuote(
  quoteId: string,
  productPrice: number,
  purchaser: Purchaser,
  transactionId: string,
): Promise<CheckoutResult> {
  return post("/accept", { quoteId, productPrice, purchaser, transactionId });
}

/** Ask the backend to decline the quote (conversion tracking). */
export function declineQuote(quoteId: string): Promise<CheckoutResult> {
  return post("/decline", { quoteId });
}

@@ -1,12 +1,25 @@
 import { useRef, useState } from "react";
 import type { ReactSpotWidgetRef } from "@getspot/spot-widget-react";
-import type { QuoteItem, SelectionData } from "@getspot/spot-widget";
+import type { Quote, QuoteItem, SelectionData } from "@getspot/spot-widget";
 import { apiConfig } from "./config";
 import { buildDefaultQuoteRequest } from "./defaultQuote";
 import { QuoteForm } from "./components/QuoteForm";
 import { WidgetPanel } from "./components/WidgetPanel";
 import { PurchaserForm } from "./components/PurchaserForm";
-import type { Purchaser } from "./types";
+import { acceptQuote, declineQuote, type CheckoutResult, type Purchaser } from "./bff";
+
+/**
+ * The API returns `expiresAt` and the widget passes the quote through untouched,
+ * but the published `Quote` type omits it. ISO8601 string, not a Date.
+ */
+type QuoteWithExpiry = Quote & { expiresAt?: string };
+
+/** True only when the quote is known to have expired; unknown means proceed. */
+function isExpired(expiresAt: string | null): boolean {
+  if (!expiresAt) return false;
+  const at = new Date(expiresAt).getTime();
+  return Number.isFinite(at) && at <= Date.now();
+}
 
 export function App() {
   // Hold the initial quote request stable so editing the form never remounts
@@ -21,7 +34,17 @@ export function App() {
     lastName: "Purchaser",
     email: "[email protected]",
   });
-  const [checkoutIntent, setCheckoutIntent] = useState<SelectionData | null>(null);
+  const [checkoutResult, setCheckoutResult] = useState<CheckoutResult | null>(null);
+
+  // Only the submit handler reads this, so a ref rather than state.
+  const quoteExpiryRef = useRef<string | null>(null);
+
+  /**
+   * Identifies this order. The server derives the real idempotency key
+   * (transactionItemId) from it, so it must stay stable across retries. Real
+   * integrations should send their own order id.
+   */
+  const transactionIdRef = useRef<string>(crypto.randomUUID());
 
   const dirty = JSON.stringify(draft) !== JSON.stringify(applied);
 
@@ -41,8 +64,54 @@ export function App() {
     await handleCheckout(widgetRef.current?.getSelection() ?? null);
   }
 
-  function handleCheckout(selection: SelectionData | null) {
-    setCheckoutIntent(selection);
+  async function handleCheckout(selection: SelectionData | null) {
+    setCheckoutResult(null);
+    if (!selection?.quoteId) return;
+
+    // The quote describes `applied`; unapplied edits in `draft` were never
+    // quoted, so re-quote before submitting.
+    if (dirty) {
+      setCheckoutResult({
+        ok: false,
+        status: 0,
+        body: {
+          error:
+            "The booking changed since it was quoted. Apply the changes to re-quote, then confirm.",
+        },
+      });
+      return;
+    }
+
+    // Re-quote rather than submit an id Spot will reject. updateQuote() fires
+    // onQuoteRetrieved again, refreshing the stored expiry.
+    if (isExpired(quoteExpiryRef.current)) {
+      const requoted = await widgetRef.current?.updateQuote(applied);
+      setCheckoutResult({
+        ok: false,
+        status: 0,
+        body: {
+          error: requoted
+            ? "That quote had expired, so it was refreshed. Review the new quote and confirm again."
+            : "That quote had expired and could not be refreshed. Please try again.",
+        },
+      });
+      return;
+    }
+
+    try {
+      const result =
+        selection.status === "QUOTE_ACCEPTED"
+          ? await acceptQuote(
+              selection.quoteId,
+              applied.productPrice,
+              purchaser,
+              transactionIdRef.current,
+            )
+          : await declineQuote(selection.quoteId);
+      setCheckoutResult(result);
+    } catch (error) {
+      setCheckoutResult({ ok: false, status: 0, body: { error: (error as Error).message } });
+    }
   }
 
   return (
@@ -72,23 +141,26 @@ export function App() {
               widgetRef={widgetRef}
               apiConfig={apiConfig}
               quoteRequestData={initialQuoteRef.current}
-              onQuoteRetrieved={() => {}}
+              onQuoteRetrieved={(quote) => {
+                quoteExpiryRef.current = (quote as QuoteWithExpiry).expiresAt ?? null;
+              }}
               onOptIn={() => {}}
               onOptOut={() => {}}
               onError={() => {}}
               onNoMatchingQuote={() => {}}
             />
 
-            {checkoutIntent && (
+            {checkoutResult && (
               <section className="panel panel--seam">
                 <div className="panel__header">
-                  <h2>Selection captured</h2>
+                  <h2>Backend response</h2>
                 </div>
-                <p className="muted">
-                  status <code>{checkoutIntent.status}</code>, quote{" "}
-                  <code>{checkoutIntent.quoteId ?? "(none)"}</code>. Next we send
-                  this to the backend.
+                <p className={checkoutResult.ok ? "notice notice--ok" : "notice notice--error"}>
+                  {checkoutResult.status === 0
+                    ? "Could not reach the backend. Is it running?"
+                    : `HTTP ${checkoutResult.status}${checkoutResult.ok ? " (success)" : ""}`}
                 </p>
+                <pre className="log__detail">{JSON.stringify(checkoutResult.body, null, 2)}</pre>
               </section>
             )}
           </div>

import { createHmac, timingSafeEqual } from "node:crypto";
import { config } from "../config.js";

/**
 * Verify Spot's X-Spot-Signature exactly as the platform produces it:
 * hex HMAC-SHA256 over the RAW request body bytes, keyed by
 * `${partnerId}:${hmacSecret}`. The raw bytes matter: re-serializing the parsed
 * JSON could reorder keys or reformat dates and break the comparison.
 */
export function verifySignature(
  rawBody: Buffer,
  signatureHeader: string | undefined,
): boolean {
  if (!signatureHeader) {
    return false;
  }
  const key = `${config.partnerId}:${config.webhookHmacSecret}`;
  const expectedHex = createHmac("sha256", key).update(rawBody).digest("hex");

  const expected = Buffer.from(expectedHex, "hex");
  const provided = Buffer.from(signatureHeader, "hex");
  if (expected.length === 0 || expected.length !== provided.length) {
    return false;
  }
  return timingSafeEqual(expected, provided);
}

@@ -2,10 +2,23 @@ import cors from "cors";
 import express from "express";
 import { config } from "./config.js";
 import { acceptQuote, declineQuote, type SpotCallResult } from "./spot/spotClient.js";
+import { verifySignature } from "./spot/webhookSignature.js";
+
+interface RawBodyRequest extends express.Request {
+  rawBody?: Buffer;
+}
 
 const app = express();
 app.use(cors({ origin: config.frontendOrigins }));
-app.use(express.json());
+// Keep the raw body alongside the parsed JSON so the webhook route can verify
+// the HMAC over exactly the bytes that were received.
+app.use(
+  express.json({
+    verify: (req, _res, buffer) => {
+      (req as RawBodyRequest).rawBody = buffer;
+    },
+  }),
+);
 
 // ===========================================================================
 // The actual Spot integration. This is the code a partner writes.
@@ -59,6 +72,22 @@ app.post("/decline", async (req, res) => {
   await forward(res, () => declineQuote(quoteId));
 });
 
+/**
+ * Receive an outbound Spot webhook: verify the signature over the raw body and
+ * respond (401 on a bad signature so a real sender retries).
+ */
+app.post("/webhooks", (req, res) => {
+  const rawBody = (req as RawBodyRequest).rawBody ?? Buffer.alloc(0);
+  const signature = req.header("X-Spot-Signature") ?? null;
+  const verified = verifySignature(rawBody, signature ?? undefined);
+
+  if (!verified) {
+    res.status(401).json({ error: "invalid or missing X-Spot-Signature" });
+    return;
+  }
+  res.status(200).json({ received: true });
+});
+
 /** Run a Spot call and mirror its status and body back to the caller. */
 async function forward(
   res: express.Response,