WordPress, Shopify and GitHub each assume something about how your site is built. The webhook destination assumes nothing: Cituna POSTs the finished article to a URL you control, as JSON, signed so you can prove it came from us, and you decide what happens next. That makes it the right choice for a Next.js, Rails or Django app with its own database, for a headless CMS such as Strapi or Storyblok behind your own API, and for anything running through Make or n8n. Zapier has its own card, with no code to write. The delivery is outbound only (you supply the URL, we call it), so there is nothing to open up on your side beyond a single route that accepts POST and answers 2xx. This guide covers that route, the payload, and the answers Cituna understands.
What this assumes
1. Deploy a receiver before you connect
Add a POST route that checks the signature, stores the article by its idempotencyKey and answers 2xx. Read the body as raw text, since the signature covers those exact bytes, and compare signatures with a timing-safe function.
Deploy it before you connect. Cituna signs the connection ping with a secret it shows you only after the ping succeeds, so while no secret is set, the route answers pings and refuses articles.
app/api/cituna/articles/route.js
// app/api/cituna/articles/route.js in a Next.js app. Any stack works the same way.
import crypto from 'node:crypto';
export async function POST(req) {
const raw = await req.text(); // the raw body: the signature covers these exact bytes
const { event, article } = JSON.parse(raw);
const secret = process.env.CITUNA_WEBHOOK_SECRET;
// No secret yet means you are connecting: answer the ping, refuse the rest.
if (!secret) {
return event === 'ping'
? Response.json({ ok: true })
: Response.json({ error: 'Not set up yet' }, { status: 503 });
}
const ts = req.headers.get('x-cituna-timestamp') ?? '';
const sig = Buffer.from(req.headers.get('x-cituna-signature') ?? '');
const expected = Buffer.from(
crypto.createHmac('sha256', secret).update(ts + '.' + raw).digest('hex'),
);
if (sig.length !== expected.length || !crypto.timingSafeEqual(sig, expected)) {
return Response.json({ error: 'Bad signature' }, { status: 401 });
}
if (Math.abs(Date.now() - Number(ts)) > 5 * 60 * 1000) {
return Response.json({ error: 'Stale timestamp' }, { status: 401 });
}
if (event === 'ping') return Response.json({ ok: true });
// db is your own database or CMS. One row per idempotencyKey, so a retry
// or an update replaces the row instead of adding another.
const existing = await db.articles.findOne({ citunaKey: article.idempotencyKey });
await db.articles.upsert({ citunaKey: article.idempotencyKey }, {
title: article.title,
slug: article.slug,
body: article.html,
seoTitle: article.metaTitle,
seoDescription: article.description,
// An update can carry publish: false. It never takes a live page down.
published: Boolean(existing?.published || article.publish),
});
// Optional: where the article lives, so later articles can link to it.
return Response.json({ url: 'https://yoursite.com/blog/' + article.slug });
}
2. Connect the URL in Cituna
Choose the brand in the top bar, open Integrations and click Connect on the Webhook card. Enter the route's full https address under Endpoint URL and click Connect webhook. Cituna sends a signed ping and saves nothing unless your endpoint answers 2xx, so you never end up with a connection that only looks healthy.
The URL must be https and public. Localhost and private network addresses are refused, and redirects are not followed, so connect the final address. The address is checked again at every send, because a name can be pointed at a private address after it was approved.
3. Store the signing secret and deploy again
Click Copy secret, store it as CITUNA_WEBHOOK_SECRET, then click I've saved it. It starts with whsec_ and is shown once: if you lose it, disconnect and connect again for a new one.
Deploy with the secret. From then on your endpoint checks the signature on every request, pings included, and answers 401 to any request that fails it. Each request carries x-cituna-timestamp, in milliseconds, and x-cituna-signature, the hex HMAC-SHA256 of the timestamp, a dot and the raw body, keyed with your secret.

4. Map the payload to your model
Every article arrives as both html and markdown. The html is block markup ending in a JSON-LD script with the structured data, the markdown is the same article without it, and neither repeats the title. metaTitle and description are for the title tag and meta description, image is the hero as base64 or null, and the same idempotencyKey comes in the payload and in the idempotency-key header on every send.
publish true means put it live, and false means keep it unpublished for review. An update can carry false, so never take a live page down because of it.
What Cituna sends (long values shortened)
{
"event": "article.created",
"article": {
"idempotencyKey": "article:example.com:how-to-store-sourdough-bread",
"siteDomain": "example.com",
"title": "How to store sourdough bread",
"metaTitle": "How to store sourdough bread so it stays fresh",
"slug": "how-to-store-sourdough-bread",
"markdown": "Keep a cut loaf cut side down on a wooden board for the first day, then in a paper bag.\n\n## Why sourdough keeps longer\n\nIts acidity slows mould, so a good loaf stays fresh for three to four days.\n\n...",
"html": "<!-- wp:paragraph --><p>Keep a cut loaf cut side down on a wooden board for the first day, then in a paper bag.</p><!-- /wp:paragraph -->\n\n<!-- wp:heading --><h2 class=\"wp-block-heading\">Why sourdough keeps longer</h2><!-- /wp:heading -->\n\n...\n\n<!-- wp:html -->\n<script type=\"application/ld+json\">...</script>\n<!-- /wp:html -->",
"description": "Where to keep a sourdough loaf, how long it lasts, and when to freeze it.",
"tags": ["bread", "storage"],
"faqs": [{ "q": "Can you freeze sourdough?", "a": "Yes. Slice it first, then toast the slices straight from the freezer." }],
"imageAlt": "A sliced sourdough loaf on a wooden board",
"image": {
"filename": "how-to-store-sourdough-bread-hero.webp",
"mime": "image/webp",
"width": 1536,
"height": 1024,
"alt": "A sliced sourdough loaf on a wooden board",
"base64": "UklGRuK..."
},
"keyword": "how to store sourdough bread",
"datePublished": "2026-10-24T09:00:00.000Z",
"dateModified": "2026-10-24T09:00:00.000Z",
"publish": false
},
"sentAt": "2026-10-24T09:00:01.482Z"
}5. Keep edits made on your side
Cituna sends a live article again when it refreshes its SEO title, description and FAQs, adds sections or links it to a newer article. Those automatic updates go only to an endpoint that answers every 2xx, the ping included, with "keepsEdits": true, and each one carries "onlyIfUnchanged": true.
Answer such an update with 409 and { "code": "site_edited" } when your copy changed since Cituna sent it, and Cituna leaves that article alone. Update on Webhook in Articles sends an article whenever you click it; once your endpoint keeps edits, that send asks too, and a site_edited answer offers Replace it on Webhook.
Keeping edits made on your side
// Replaces everything after the signature check. editedSinceCituna is your
// own flag: set it to true whenever someone edits the article on your side.
if (event === 'ping') return Response.json({ ok: true, keepsEdits: true });
const existing = await db.articles.findOne({ citunaKey: article.idempotencyKey });
if (article.onlyIfUnchanged && !existing) {
return Response.json({ code: 'site_unverified', error: 'No copy here' }, { status: 409 });
}
if (article.onlyIfUnchanged && existing.editedSinceCituna) {
return Response.json({ code: 'site_edited', error: 'Edited on our site' }, { status: 409 });
}
await db.articles.upsert({ citunaKey: article.idempotencyKey }, {
title: article.title,
slug: article.slug,
body: article.html,
seoTitle: article.metaTitle,
seoDescription: article.description,
published: Boolean(existing?.published || article.publish),
editedSinceCituna: false,
});
return Response.json({ url: 'https://yoursite.com/blog/' + article.slug, keepsEdits: true });6. Send a test delivery, then turn on daily articles
On the Webhook card, click Send test delivery. Cituna sends a ping signed with your secret and reports either that your endpoint accepted it or the exact status it answered, which tells a deploy problem apart from a signing bug.
Then open Articles. Under Where should the articles go?, choose Webhook, pick an answer under Who approves them?, and under Start writing turn on Write articles every day. The daily articles guide explains the approval choices.
Troubleshooting
Connecting fails with "Your endpoint answered 401".
Your endpoint checked the connection ping against a secret it already had, from an earlier connection, and every connection signs its ping with a new secret. Remove CITUNA_WEBHOOK_SECRET, deploy, connect again, then store the new secret and deploy once more. If a login check guards the route, let this route through.
Every signature fails even though the secret is right.
Almost always the body was parsed and re-serialised before signing. JSON.stringify does not guarantee the original key order or spacing, so the bytes differ from what we signed. Read the raw text of the request first, verify against that, and parse afterwards. In Express, express.raw({ type: 'application/json', limit: '2mb' }) on this route keeps the raw bytes and allows for a delivery with an image, which is about 1 MB.
Can I point the webhook at localhost while I develop?
No. Private and loopback addresses are refused at connect and again at every send, because a URL that resolves inside our own network is how server-side request forgery works. Use a tunnel that gives you a public HTTPS address and everything else behaves identically.
What happens if my endpoint is down when an article is written?
The article is kept in Cituna. No answer within 15 seconds, or a 408, 429 or 5xx, is tried twice more in the same run, 2 and 8 seconds apart, then again on the next run with the same article rather than a newly written one. A redirect is not followed, so connect the final address; any other 4xx leaves the article to go again on the next run.
Can my endpoint refuse an article?
Yes. Answer 422, or 400 with a problems list holding your reasons. AutoSEO rewrites the article with those reasons on the next run and keeps them for later articles, and a second refusal leaves it for you to edit in Articles. For errors on your side, answer 5xx instead, so the same article is sent again.
How long do I have to respond?
Fifteen seconds. Do the minimum synchronously (verify, store, answer 2xx) and push anything slow, such as image processing or a site rebuild, onto a background job.
Drafted with AI assistance from our own research and Search Console data, and reviewed by Rahul A before publishing. Rules and prices change; check the linked official source before you act.

