autoranko

Publishing

Publishing webhook

Publish Autoranko articles on any site you control. Connect your endpoint once, and every publish, update and unpublish arrives as a signed JSON request that your code verifies, stores and renders.

Overview

The publishing webhook is a connector, like Shopify or Ghost, for sites that have no native integration: a Next.js or Astro site, an app built with Lovable, Bolt or v0, or your own CMS. It is different from the account webhooks, which notify you about job events: this one carries the whole article so your site can publish it.

  1. Build a receiver (samples below) and deploy it on a public HTTPS URL, for example https://www.example.com/api/autoranko.
  2. In Dashboard → Integrations, configure Publishing webhook with that URL. Leave the secret empty to have one generated: it is shown once, so store it as AUTORANKO_WEBHOOK_SECRET.
  3. Saving sends a signed webhook.test event. Your endpoint answers 2xx and the connector shows as connected.
  4. From then on, publishing an article (by hand, through the API or on autopilot) sends it to your endpoint. Answer 2xx with JSON {"url": "<public URL>"} and Autoranko records that URL as the published address.
Publishing events
EventSent when
article.publishedFirst push of an article (live or draft), and when a draft or unpublished article goes live.
article.updatedYou clicked Update live (or Update draft) after editing: same article.id, higher revision.
article.unpublishedYou unpublished the article: hide its page, keep the record.
webhook.testThe Send test event button in Dashboard → Integrations. Answer 2xx and store nothing.

Images

Image URLs point to autoranko.com/media, served with long-lived caching while the site is on Autoranko and deleted 30 days after the site is removed. For pages that depend only on your own servers, download each image when you store the article and serve your copy.

Payload

Every event is a POST with a compact JSON body (Content-Type: application/json). The envelope:

Event envelope
FieldTypeDescription
idstringEvent id (UUID). Same value as the X-Autoranko-Event-Id header.
eventstringarticle.published, article.updated, article.unpublished or webhook.test.
created_atstringWhen the event was created (ISO 8601, UTC).
articleobjectThe article as it should look on your site after this event.

The article object

Article fields
FieldTypeDescription
idintegerStable article id. Key your storage on it.
site_idintegerThe Autoranko site the article belongs to.
revisionintegerGrows by one with every push. Ignore anything not newer than what you stored.
statusstring"published" (show it) or "draft" (store it, don't show it).
titlestringRender it as the page's only <h1>.
slugstringSuggested URL slug. Fixed once the article was first published.
meta_descriptionstringFor <meta name="description"> and og:description.
excerptstringShort summary for your blog index (300 characters at most).
htmlstringThe body: headings start at <h2>, never an <h1>; images are <figure><img> with alt, width and height.
featured_imageobject | null{url, alt, width, height} of the hero image.
imagesarrayThe images used inside html, same shape.
faqarray[{question, answer}]: the FAQ exactly as it appears in html.
json_ldobject | nullschema.org graph (Article, plus FAQPage when there is an FAQ) to print in a <script type="application/ld+json">.
languagestringBCP 47 language tag of the article, or empty.
target_keywordstringThe keyword the article targets, or empty.
published_atstring | nullFirst publication date. Null for an article that was never live.
updated_atstringLast real content change. Use it for <lastmod> in your sitemap.
urlstring | nullThe URL your endpoint returned last time, if any.
article.updated (pretty-printed; the real body is compact)
{
  "id": "5f0c6c1e-2b7a-4d8e-9a51-3c2f8e7d1a90",
  "event": "article.updated",
  "created_at": "2026-11-07T09:30:12.000Z",
  "article": {
    "id": 42,
    "site_id": 7,
    "revision": 3,
    "status": "published",
    "title": "How to water a vegetable garden",
    "slug": "how-to-water-a-vegetable-garden",
    "meta_description": "When, how often and how much to water vegetables, from seedlings to harvest, with a simple weekly schedule.",
    "excerpt": "When, how often and how much to water vegetables, from seedlings to harvest.",
    "html": "<p>Water deeply, early in the morning…</p>\n<h2>How often to water</h2>\n<figure><img src=\"https://autoranko.com/media/3b5d…e1.jpg\" alt=\"Drip line between lettuce rows\" width=\"1600\" height=\"900\" loading=\"lazy\" decoding=\"async\"></figure>\n…",
    "featured_image": {
      "url": "https://autoranko.com/media/9c1a…7f.jpg",
      "alt": "Watering can over young tomato plants",
      "width": 1600,
      "height": 900
    },
    "images": [
      {
        "url": "https://autoranko.com/media/3b5d…e1.jpg",
        "alt": "Drip line between lettuce rows",
        "width": 1600,
        "height": 900
      }
    ],
    "faq": [
      {
        "question": "Is it better to water in the morning or at night?",
        "answer": "Morning: leaves dry quickly…"
      }
    ],
    "json_ld": {
      "@context": "https://schema.org",
      "@graph": [
        {
          "@type": "Article",
          "headline": "How to water a vegetable garden"
        },
        {
          "@type": "FAQPage"
        }
      ]
    },
    "language": "en",
    "target_keyword": "water vegetable garden",
    "published_at": "2026-11-05T08:00:00.000Z",
    "updated_at": "2026-11-07T09:29:58.000Z",
    "url": "https://www.example.com/blog/how-to-water-a-vegetable-garden"
  }
}

Signatures

Each delivery is signed with your endpoint's secret. Anyone can POST to a public URL, so check the signature before you trust anything in the body.

Delivery headers
HeaderExampleDescription
X-Autoranko-Signature-V1t=1767225600,v1=b3dd…2ad6Timestamped HMAC-SHA256 signature. Verify this one.
X-Autoranko-Signaturesha256=5c1e…Legacy body-only HMAC, kept for older receivers. It has no timestamp, so it can't stop replays.
X-Autoranko-Eventarticle.updatedThe event name, also in the body.
X-Autoranko-Event-Id5f0c6c1e-…Equals body.id. The same on the retry of one delivery.
X-Autoranko-Deliveryc8a2…Unique per attempt. Log it when you debug.
Idempotency-Key42:3"<article.id>:<revision>": stable for one operation, whatever the attempt.
X-Autoranko-Article-Revision3The article's revision, also in body.article.revision.
User-AgentAutorankoPublisher/1.0Every publishing delivery.

X-Autoranko-Signature-V1 has the form t=<unix seconds>,v1=<hex>. To verify it:

  1. Read the raw request body as bytes, before any JSON parsing or re-serialization.
  2. Split the header on commas and read t and v1.
  3. Reject the request when t is more than 300 seconds away from your clock. That stops someone from replaying a captured delivery later.
  4. Compute HMAC-SHA256 of t, a period, then the raw body (<t>.<body>), keyed with your secret, as lowercase hex.
  5. Compare it with v1 in constant time, and answer 401 when it doesn't match.

Keep the secret on the server

Never put the secret in client-side code or in your repository, and never log it. If it leaks, edit the connector in Dashboard → Integrations with a new secret, then update your environment.

Idempotency and ordering

  • Store by article.id. An article.updated or a second article.published for the same id updates the record you have; it never creates a second article.
  • Keep the revision. It grows with every push of that article. Deliveries can arrive out of order (a retry of an older push can land after a newer one), so ignore any event whose revision is not greater than the one you stored, and still answer 2xx.
  • Deduplicate on Idempotency-Key. It is <article.id>:<revision>: the same for every attempt of one operation, different for the next operation. X-Autoranko-Event-Id is stable across the retry of one delivery; X-Autoranko-Delivery changes on every attempt.
  • Unpublish hides, it doesn't delete. article.unpublished arrives with status draft. Publishing the article again sends article.published with a higher revision.
Delivery rules
Timeout20 seconds per attempt
RetriesOne more attempt, 2 seconds later, after a network error, a timeout or a 5xx
SuccessAny 2xx; JSON {"url": …} sets the article's published URL
FailureThe article returns to review with an error starting "Publishing failed:"

Receivers

Complete receivers that verify the signature with the 300-second tolerance, deduplicate, respect the revision order and answer with the article's URL. Replace the in-memory maps with your database.

// receiver.mjs — Node.js 18+, no dependencies: node receiver.mjs
import { createServer } from "node:http";
import { createHmac, timingSafeEqual } from "node:crypto";

const SECRET = process.env.AUTORANKO_WEBHOOK_SECRET;
const TOLERANCE_SECONDS = 300;
const articles = new Map(); // article.id -> article (use your database)
const seenKeys = new Set(); // processed Idempotency-Key values (use your database)

/** True when X-Autoranko-Signature-V1 matches the raw body and is less than 5 minutes old. */
export function verify(rawBody, header, secret = SECRET, now = Math.floor(Date.now() / 1000)) {
  const parts = Object.fromEntries(
    String(header || "").split(",").map((part) => part.trim().split("="))
  );
  const t = Number(parts.t);
  if (!Number.isInteger(t) || !/^[0-9a-f]{64}$/.test(parts.v1 || "")) return false;
  if (Math.abs(now - t) > TOLERANCE_SECONDS) return false;
  const expected = createHmac("sha256", secret).update(`${t}.`).update(rawBody).digest();
  return timingSafeEqual(expected, Buffer.from(parts.v1, "hex"));
}

const publicUrl = (article) => `https://www.example.com/blog/${article.slug}`;

function reply(res, status, body) {
  res.writeHead(status, { "Content-Type": "application/json" });
  res.end(JSON.stringify(body));
}

const server = createServer((req, res) => {
  if (req.method !== "POST" || req.url !== "/api/autoranko") return reply(res, 404, { error: "not found" });
  const chunks = [];
  req.on("data", (chunk) => chunks.push(chunk));
  req.on("end", () => {
    const raw = Buffer.concat(chunks); // the exact bytes that were signed
    if (!SECRET || !verify(raw, req.headers["x-autoranko-signature-v1"])) {
      return reply(res, 401, { error: "invalid signature" });
    }
    const { event, article } = JSON.parse(raw.toString("utf8"));
    if (event === "webhook.test") return reply(res, 200, { ok: true }); // never stored

    const key = String(req.headers["idempotency-key"] || "");
    const stored = articles.get(article.id);
    // A repeat, or an older revision arriving late: acknowledge and change nothing.
    if (seenKeys.has(key) || (stored && stored.revision >= article.revision)) {
      return reply(res, 200, { url: stored?.status === "published" ? publicUrl(stored) : null });
    }
    seenKeys.add(key);
    const next = event === "article.unpublished" ? { ...article, status: "draft" } : article;
    articles.set(article.id, next); // upsert by article.id: an update never creates a second article
    reply(res, 200, { url: next.status === "published" ? publicUrl(next) : null });
  });
});

server.listen(3000, () => console.log("Listening on http://localhost:3000/api/autoranko"));

Next.js route handler

app/api/autoranko/route.ts
// app/api/autoranko/route.ts — Next.js App Router
import { createHmac, timingSafeEqual } from "node:crypto";

const TOLERANCE_SECONDS = 300;

function verify(raw: string, header: string | null, secret: string): boolean {
  const parts = Object.fromEntries((header || "").split(",").map((p) => p.trim().split("=")));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || !/^[0-9a-f]{64}$/.test(parts.v1 || "")) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > TOLERANCE_SECONDS) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${raw}`).digest();
  return timingSafeEqual(expected, Buffer.from(parts.v1, "hex"));
}

export async function POST(req: Request) {
  const raw = await req.text(); // read the body once, before parsing it
  if (!verify(raw, req.headers.get("x-autoranko-signature-v1"), process.env.AUTORANKO_WEBHOOK_SECRET ?? "")) {
    return Response.json({ error: "invalid signature" }, { status: 401 });
  }
  const { event, article } = JSON.parse(raw);
  if (event === "webhook.test") return Response.json({ ok: true });
  // Upsert by article.id only when article.revision is newer than the stored one, and skip
  // Idempotency-Key values you already processed (see the Node.js sample above).
  const url = await saveArticle(event, article); // your storage; returns the public URL or null
  return Response.json({ url });
}

Render the page well

  • Server-render each article: title in <title> and in one <h1>, meta description, a canonical link to its own URL, Open Graph tags.
  • Print article.json_ld in a <script type="application/ld+json"> tag, and pass the body through an allow-list HTML sanitizer.
  • List published articles in your sitemap with <lastmod> set to article.updated_at, the real date of the last change.

Built your site with Lovable, Cursor, Claude Code, Bolt or v0? Dashboard → Integrations has a copy-paste prompt that asks your tool for all of the above, with tests. Review the code it writes before you deploy it.

Testing

A known-good input for your verifier: with this secret and this exact body, a timestamp of 1767225600 must produce this header. Pass the timestamp as now to the sample verify functions, since it is older than 300 seconds.

Signature test vector
Secretwhsec_test_9f2c4e7a1b3d5f60718293a4b5c6d7e8
Timestamp1767225600
Headert=1767225600,v1=b3dd581c972f50a98ab65be2d47340782ada16863677723c3eefa448261f2ad6
Body (exact bytes, compact)
{"id":"5f0c6c1e-2b7a-4d8e-9a51-3c2f8e7d1a90","event":"article.published","created_at":"2026-01-01T00:00:00.000Z","article":{"id":42,"site_id":7,"revision":1,"status":"published","title":"How to water a vegetable garden","slug":"how-to-water-a-vegetable-garden","meta_description":"When, how often and how much to water vegetables, from seedlings to harvest.","excerpt":"When, how often and how much to water vegetables.","html":"<p>Water deeply, early in the morning.</p>","featured_image":null,"images":[],"faq":[],"json_ld":null,"language":"en","target_keyword":"water vegetable garden","published_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","url":null}}

To try a running receiver, sign a request yourself with the test secret (start the receiver with the same value in AUTORANKO_WEBHOOK_SECRET). Expect a 2xx with the URL; send it again and nothing changes; alter one character of the body and expect 401.

Shell
SECRET='whsec_test_9f2c4e7a1b3d5f60718293a4b5c6d7e8'
BODY='{"id":"test-1","event":"article.published","created_at":"2026-01-01T00:00:00.000Z","article":{"id":42,"revision":1,"status":"published","slug":"hello"}}'
T=$(date +%s)
SIG=$(printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.*= //')
curl -sS -X POST http://localhost:3000/api/autoranko \
  -H 'Content-Type: application/json' \
  -H 'X-Autoranko-Event: article.published' \
  -H "X-Autoranko-Signature-V1: t=$T,v1=$SIG" \
  -H 'Idempotency-Key: 42:1' \
  -H 'X-Autoranko-Article-Revision: 1' \
  --data "$BODY"
The test secret is public. Use it only on your machine; in production, use the secret of your connector. In the dashboard, Send test event delivers a signed webhook.test to your real endpoint.