The publishing webhook, in full.

// app/api/hoxigen/route.js — a complete Version 1 receiver.
// Supply saveArticle(); everything else here is the whole contract.
import crypto from "node:crypto";
import { saveArticle } from "@/lib/your-article-store";
import { verifyHoxigenSignature } from "@/lib/hoxigen-signature";

const MAX_BODY = 1_000_000;

export async function POST(req) {
  // 1. Raw bytes first. The signature covers what was sent, not what JSON.parse
  //    gives back, and an unsigned request must not be able to cost you a parse.
  const raw = await req.text();
  if (raw.length > MAX_BODY) {
    return Response.json({ error: "Payload too large" }, { status: 413 });
  }
  const secret = process.env.HOXIGEN_WEBHOOK_SECRET;
  if (!secret || !verifyHoxigenSignature(raw, req.headers.get("x-hoxigen-signature"), secret)) {
    return Response.json({ error: "Invalid signature" }, { status: 401 });
  }

  // 2. Only now is it safe to parse.
  let payload;
  try {
    payload = JSON.parse(raw);
  } catch {
    return Response.json({ error: "Invalid JSON" }, { status: 400 });
  }
  const data = payload?.data ?? {};

  if (payload?.event === "webhook.test") {
    // Version 1: acknowledge, advertise nothing. Claiming a capability you have
    // not implemented is how a refresh overwrites the wrong article.
    return Response.json({ received: true });
  }

  if (payload?.event === "article.published") {
    if (typeof data.id !== "string" || !data.id.trim()) {
      return Response.json({ error: "Missing data.id" }, { status: 400 });
    }
    // Deduplicate on data.id: retries redeliver the same article, and the stored
    // id, slug and public URL must not move when they do. Commit before you
    // answer — a 200 tells Hoxigen the article is durably yours.
    await saveArticle(data);
    return Response.json({ received: true });
  }

  // Anything you do not implement fails loudly. A 200 here would tell Hoxigen a
  // refresh landed when nothing happened.
  return Response.json({ error: "Unsupported event" }, { status: 400 });
}

// app/api/hoxigen-webhook/route.js (Next.js App Router)
// Implement this adapter with your existing DB, validation and transactions.
// Do not advertise Version 2 until all three methods satisfy the receiver spec.
import crypto from "node:crypto";
import { articles, validateWebhookPayload } from "@/lib/your-article-store";

export async function POST(req) {
  const raw = await req.text();
  const expected = "sha256=" + crypto
    .createHmac("sha256", process.env.HOXIGEN_WEBHOOK_SECRET)
    .update(raw).digest("hex");
  const a = Buffer.from(req.headers.get("x-hoxigen-signature") || "");
  const b = Buffer.from(expected);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return Response.json({ error: "Invalid signature" }, { status: 401 });
  }
  let payload;
  try {
    payload = validateWebhookPayload(JSON.parse(raw));
  } catch {
    return Response.json({ error: "Invalid payload" }, { status: 400 });
  }
  const { event, data } = payload;
  if (event === "webhook.test") {
    return Response.json({ received: true, contract_version: 2,
      capabilities: ["article.published", "article.lookup", "article.updated"] });
  }
  if (event === "article.published") {
    await articles.publishIdempotently(data); // preserve existing ID, slug, URL
    return Response.json({ received: true });
  }
  if (payload.contract_version !== 2) {
    return Response.json({ error: "Version 2 required" }, { status: 400 });
  }
  if (event === "article.lookup") {
    const target = await articles.findExactlyByPublicUrl(data.target_url);
    if (!target) return Response.json({ error: "Not found" }, { status: 404 });
    return Response.json({ received: true, contract_version: 2, target });
  }
  if (event === "article.updated") {
    // Adapter atomically checks target ID + URL, already-applied revision,
    // then base revision; writes content + revision without changing the URL.
    const result = await articles.updateIfRevisionMatches(data);
    if (result === "conflict") {
      return Response.json({ error: "Article revision conflict" }, { status: 409 });
    }
    if (result !== "committed" && result !== "identical-retry") {
      return Response.json({ error: "Not found" }, { status: 404 });
    }
    return Response.json({ received: true, contract_version: 2,
      revision_id: data.revision_id });
  }
  return Response.json({ error: "Unsupported event" }, { status: 400 });
}

Hoxigen blog webhook — Version 2 receiver spec

Transport and authentication:
  HTTP POST to the existing endpoint; Content-Type: application/json.
  X-Hoxigen-Event equals the payload event. Version 2 requests include
  X-Hoxigen-Contract: 2 and top-level contract_version: 2.
  X-Hoxigen-Timestamp: <unix seconds>; payload timestamp: ISO 8601 string.
  X-Hoxigen-Signature: sha256=<hex>, HMAC-SHA256 of the raw request body
  with HOXIGEN_WEBHOOK_SECRET. Read raw bytes before JSON parsing, compare
  signatures in constant time, and return 401 on mismatch. Never expose secrets.
  Validate event, field types and nonempty IDs/URLs/revisions before writing.
  Return 400 for invalid requests; never acknowledge a write before it commits.

webhook.test (no writes):
  Request: { "event": "webhook.test", "contract_version": 2, "timestamp": "<ISO>",
    "data": { "id": "<test ID>", "message": "<test message>",
      "capabilities": ["article.published", "article.lookup", "article.updated"] } }
  HTTP 200: { "received": true, "contract_version": 2,
    "capabilities": ["article.published", "article.lookup", "article.updated"] }
  Advertise only capabilities that are fully implemented and tested.

article.published (Version 1 compatible):
  Accept the existing payload without contract_version or X-Hoxigen-Contract.
  data contains id, title, slug, content_html, content_markdown, meta_description,
  focus_keyword, featured_image_url, tags, author, published_at and json_ld.
  Deduplicate by data.id. Persist before returning HTTP 200 { "received": true }.
  Keep the stored article ID and public URL stable on redelivery. Store an opaque,
  nonempty revision_id that changes whenever content is edited, including CMS edits.
  Inject json_ld script blocks into the page head. Rebuild/cache work may run async.

article.lookup (read only):
  Request: { "event": "article.lookup", "contract_version": 2, "timestamp": "<ISO>",
    "data": { "target_url": "https://site.example/blog/post" } }
  Resolve exactly one article by its public URL. Canonicalization removes the
  fragment and one trailing path slash only; origin, path and query must match.
  Use HTTP(S) URLs without credentials. Never guess by title, slug similarity,
  or a URL on another origin. Missing or ambiguous targets fail with non-2xx.
  HTTP 200: { "received": true, "contract_version": 2, "target": {
    "id": "<stored article ID>", "url": "https://site.example/blog/post",
    "revision_id": "<current revision>", "title": "<title>",
    "content_html": "<article HTML>" } }
  All target fields must be nonempty strings. Keep responses below 1,000,000 bytes.

article.updated (replace the exact existing article, never insert):
  Request: { "event": "article.updated", "contract_version": 2, "timestamp": "<ISO>",
    "data": { <all article.published fields>,
      "id": "<refresh draft ID>", "target_id": "<stored article ID>",
      "target_url": "https://site.example/blog/post",
      "base_revision_id": "<revision returned by lookup>",
      "revision_id": "<refresh draft ID>" } }
  data.id and data.revision_id must match. target_id AND target_url must identify
  the same existing article. Preserve its stored ID, slug and public URL even
  when the incoming draft's id or slug differs. Replace supported content fields.
  Atomically compare base_revision_id with the current revision and write the
  content plus revision_id in one transaction/conditional write. Every CMS edit
  must change that revision too. If the base no longer matches, return HTTP 409
  { "error": "Article revision conflict" } without changing anything.
  Check revision_id before comparing the base: if it is already the current
  revision, return success without reapplying content. Otherwise a stale base
  returns 409, including an old retry after a newer edit. This makes retries
  idempotent without rolling back later edits. Never reuse a revision_id for
  different content; each refresh draft has its own immutable revision ID.
  Only after durable commit, HTTP 200:
    { "received": true, "contract_version": 2, "revision_id": "<refresh draft ID>" }
  Never return a generic Version 1 acknowledgement for lookup or update.
  Failed deliveries retry after 1m, 5m, 30m, 2h and 6h; unsupported events fail
  with non-2xx instead of pretending an update succeeded.