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. The url is the
    // article's public address: Hoxigen links the article to it.
    const { url } = await saveArticle(data);
    return Response.json({ received: true, url });
  }

  // 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 3 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: 3,
      capabilities: ["article.published", "article.lookup", "article.updated"] });
  }
  if (event === "article.published") {
    // preserve existing ID, slug, URL; answer with the article's public address
    const stored = await articles.publishIdempotently(data);
    return Response.json({ received: true, id: stored.id, url: stored.url });
  }
  // requests keep the Version 2 format: only the answers say 3
  if (payload.contract_version !== 2) {
    return Response.json({ error: "Version 2 request format 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: 3, 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: 3,
      revision_id: data.revision_id });
  }
  return Response.json({ error: "Unsupported event" }, { status: 400 });
}

Hoxigen blog webhook — Version 3 receiver spec

Versions: Version 2 added article.lookup and article.updated (refresh in place).
Version 3 adds the article's public URL to every article.published answer.
Requests are the same in both: lookup and update carry contract_version: 2.
A receiver states its version in its answers, above all to webhook.test.

Transport and authentication:
  HTTP POST to the existing endpoint; Content-Type: application/json.
  X-Hoxigen-Event equals the payload event. Lookup, update and test requests
  include X-Hoxigen-Contract: 2 and top-level contract_version: 2 (the request
  format, unchanged in Version 3). Accept exactly that value.
  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": 3,
    "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, then return HTTP 200
    { "received": true, "id": "<stored article ID>", "url": "https://site.example/blog/post" }
  url is the article's absolute public address (HTTP(S), no credentials); Hoxigen
  shows it as the article's live link. A redelivery answers with the same ID and URL.
  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": 3, "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": 3, "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.