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.
- Build a receiver (samples below) and deploy it on a public HTTPS URL, for example
https://www.example.com/api/autoranko. - 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. - Saving sends a signed webhook.test event. Your endpoint answers 2xx and the connector shows as connected.
- 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.
| Event | Sent when |
|---|---|
article.published | First push of an article (live or draft), and when a draft or unpublished article goes live. |
article.updated | You clicked Update live (or Update draft) after editing: same article.id, higher revision. |
article.unpublished | You unpublished the article: hide its page, keep the record. |
webhook.test | The Send test event button in Dashboard → Integrations. Answer 2xx and store nothing. |
Images
Payload
Every event is a POST with a compact JSON body (Content-Type: application/json). The envelope:
| Field | Type | Description |
|---|---|---|
id | string | Event id (UUID). Same value as the X-Autoranko-Event-Id header. |
event | string | article.published, article.updated, article.unpublished or webhook.test. |
created_at | string | When the event was created (ISO 8601, UTC). |
article | object | The article as it should look on your site after this event. |
The article object
| Field | Type | Description |
|---|---|---|
id | integer | Stable article id. Key your storage on it. |
site_id | integer | The Autoranko site the article belongs to. |
revision | integer | Grows by one with every push. Ignore anything not newer than what you stored. |
status | string | "published" (show it) or "draft" (store it, don't show it). |
title | string | Render it as the page's only <h1>. |
slug | string | Suggested URL slug. Fixed once the article was first published. |
meta_description | string | For <meta name="description"> and og:description. |
excerpt | string | Short summary for your blog index (300 characters at most). |
html | string | The body: headings start at <h2>, never an <h1>; images are <figure><img> with alt, width and height. |
featured_image | object | null | {url, alt, width, height} of the hero image. |
images | array | The images used inside html, same shape. |
faq | array | [{question, answer}]: the FAQ exactly as it appears in html. |
json_ld | object | null | schema.org graph (Article, plus FAQPage when there is an FAQ) to print in a <script type="application/ld+json">. |
language | string | BCP 47 language tag of the article, or empty. |
target_keyword | string | The keyword the article targets, or empty. |
published_at | string | null | First publication date. Null for an article that was never live. |
updated_at | string | Last real content change. Use it for <lastmod> in your sitemap. |
url | string | null | The URL your endpoint returned last time, if any. |
{
"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.
| Header | Example | Description |
|---|---|---|
X-Autoranko-Signature-V1 | t=1767225600,v1=b3dd…2ad6 | Timestamped HMAC-SHA256 signature. Verify this one. |
X-Autoranko-Signature | sha256=5c1e… | Legacy body-only HMAC, kept for older receivers. It has no timestamp, so it can't stop replays. |
X-Autoranko-Event | article.updated | The event name, also in the body. |
X-Autoranko-Event-Id | 5f0c6c1e-… | Equals body.id. The same on the retry of one delivery. |
X-Autoranko-Delivery | c8a2… | Unique per attempt. Log it when you debug. |
Idempotency-Key | 42:3 | "<article.id>:<revision>": stable for one operation, whatever the attempt. |
X-Autoranko-Article-Revision | 3 | The article's revision, also in body.article.revision. |
User-Agent | AutorankoPublisher/1.0 | Every publishing delivery. |
X-Autoranko-Signature-V1 has the form t=<unix seconds>,v1=<hex>. To verify it:
- Read the raw request body as bytes, before any JSON parsing or re-serialization.
- Split the header on commas and read
tandv1. - Reject the request when
tis more than 300 seconds away from your clock. That stops someone from replaying a captured delivery later. - Compute HMAC-SHA256 of
t, a period, then the raw body (<t>.<body>), keyed with your secret, as lowercase hex. - Compare it with v1 in constant time, and answer 401 when it doesn't match.
Keep the secret on the server
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.
| Timeout | 20 seconds per attempt |
|---|---|
| Retries | One more attempt, 2 seconds later, after a network error, a timeout or a 5xx |
| Success | Any 2xx; JSON {"url": …} sets the article's published URL |
| Failure | The 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"));# receiver.py — Python 3.9+ with Flask:
# AUTORANKO_WEBHOOK_SECRET=... flask --app receiver run --port 3000
import hashlib
import hmac
import json
import os
import time
from flask import Flask, jsonify, request
SECRET = os.environ.get("AUTORANKO_WEBHOOK_SECRET", "").encode()
TOLERANCE_SECONDS = 300
app = Flask(__name__)
articles = {} # article id -> article (use your database)
seen_keys = set() # processed Idempotency-Key values (use your database)
def verify(raw, header, secret=SECRET, now=None):
"""True when X-Autoranko-Signature-V1 matches the raw body and is less than 5 minutes old."""
parts = dict(p.strip().split("=", 1) for p in (header or "").split(",") if "=" in p)
try:
t = int(parts.get("t", ""))
except ValueError:
return False
now = int(time.time()) if now is None else now
if not secret or abs(now - t) > TOLERANCE_SECONDS:
return False
expected = hmac.new(secret, f"{t}.".encode() + raw, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts.get("v1", ""))
def public_url(article):
return f"https://www.example.com/blog/{article['slug']}"
@app.post("/api/autoranko")
def receive():
raw = request.get_data() # the exact bytes that were signed
if not verify(raw, request.headers.get("X-Autoranko-Signature-V1", "")):
return jsonify(error="invalid signature"), 401
payload = json.loads(raw)
event, article = payload["event"], payload["article"]
if event == "webhook.test":
return jsonify(ok=True) # never stored
key = request.headers.get("Idempotency-Key", "")
stored = articles.get(article["id"])
# A repeat, or an older revision arriving late: acknowledge and change nothing.
if key in seen_keys or (stored and stored["revision"] >= article["revision"]):
return jsonify(url=public_url(stored) if stored and stored["status"] == "published" else None)
seen_keys.add(key)
if event == "article.unpublished":
article["status"] = "draft"
articles[article["id"]] = article # upsert by id: an update never creates a second article
return jsonify(url=public_url(article) if article["status"] == "published" else None)Next.js route handler
// 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.
| Secret | whsec_test_9f2c4e7a1b3d5f60718293a4b5c6d7e8 |
|---|---|
| Timestamp | 1767225600 |
| Header | t=1767225600,v1=b3dd581c972f50a98ab65be2d47340782ada16863677723c3eefa448261f2ad6 |
{"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.
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"