jekcms's publish API connects to n8n with just a handful of workflow nodes — handling media uploads, setting categories, and following your publishing schedule. This article documents the exact node configuration: request format, authentication, error handling, and the tradeoffs between immediate, scheduled, and draft publishing.
The publish endpoint is POST /api/v1/webhook/publish (with webhook/draft and webhook/schedule siblings for the other two publishing modes). It accepts JSON with title, content, author_id, category, featured_image (a URL), and an optional scheduled_at ISO 8601 timestamp for the schedule variant. The API key goes in the X-API-Key header, checked against the api_tokens table. Successful creation returns the new post's ID and public URL.
Minimal n8n Workflow Structure
In n8n, the minimal working workflow has four nodes: an HTTP Request to fetch source content (from OpenAI, an RSS feed, or your own source), a Code node to format the payload, an HTTP Request to call the jekcms webhook endpoint, and an IF node to route errors to a Slack notification or retry queue.
Media Handling at Scale
Media handling deserves careful attention. When you pass a featured_image URL, jekcms fetches it synchronously during the API request, converts it to AVIF, and stores it locally. If the source URL is slow to respond, your entire API request blocks. For high-volume pipelines, use the dedicated webhook/media (URL-based) or webhook/media-base64 (inline-encoded) endpoints to upload media ahead of time and pass the resulting media reference in your publish call, rather than making every publish call wait on an external image fetch.
What Can Go Wrong
The most common failure mode in an automated publishing pipeline is a network timeout on the source content fetch — not an error from the jekcms API itself. Design your workflow assuming source fetches will occasionally time out: route those failures to a retry queue or a Slack alert rather than treating every failure as fatal. The force_duplicate: false default (see below) means a retried request cannot create a second copy of the same post, so it's safe to let n8n's retry mechanism run without babysitting it.
Complete n8n Node Configuration
Here is the HTTP Request node configuration for the publish call. The Content-Type header must be application/json, and the API key must go in the X-API-Key header — never as a query parameter, where it would end up in server access logs.
// n8n HTTP Request Node Settings
Method: POST
URL: https://yoursite.com/api/v1/webhook/publish
Authentication: None (handled via header)
Headers:
X-API-Key: {{ $credentials.jekcmsApiKey }}
Content-Type: application/json
Body (JSON):
{
"title": "{{ $json.title }}",
"content": "{{ $json.content }}",
"author_id": 2,
"category": "{{ $json.category }}",
"featured_image": "{{ $json.image_url }}",
"image_alt_text": "{{ $json.image_alt }}"
}Error Handling With the IF Node
The IF node after the API call checks {{ $json.success }}. On failure, the error branch sends a Slack message containing the post title and the error message. For 409 duplicate errors specifically, we route to a separate branch that logs the duplicate but does not alert — duplicates are expected when reprocessing a content batch.
Scheduling and Publishing Cadence
jekcms supports three publishing modes through the webhook API:
- Draft mode (the safer default): use the
webhook/draftendpoint — the post is saved but stays invisible until someone reviews and publishes it from the admin panel. This is the right starting point for any new workflow or unproven content source, since nothing goes live without a human looking at it first. - Scheduled publish: use
webhook/schedulewith an ISO 8601scheduled_attimestamp (e.g.,2026-03-01T09:00:00+03:00) — jekcms publishes it at that time. Reasonable once you trust the source content and want predictable timing without reviewing every post individually. - Immediate publish: use
webhook/publishdirectly and the post goes live the moment the API call succeeds — there is no review step. If the source content is wrong, off-brand, or low-quality, it's live before anyone sees it. Treat this mode as something you graduate into after a workflow has proven itself with draft or scheduled publish, not a default to start with.
Whichever mode you choose, the decision belongs to you: jekcms doesn't force a review queue, but it also doesn't hide the risk of skipping one. For most teams, routing everything through draft or scheduled publish — and reviewing before it goes live — is the safer long-term habit, even once a pipeline is stable.
For SEO purposes, we stagger scheduled publications rather than publishing everything at once — for example, spacing posts at fixed intervals across the day using the Code node to assign sequential timestamps.
Category and Tag Automation
The API accepts category names as strings. If a category does not exist, jekcms creates it automatically with a generated slug. Tags work the same way — pass an array of strings in the tags field. This means your n8n workflow does not need to know the site's existing category IDs; it can simply pass the category name from the content source and let jekcms handle the lookup or creation.
Webhook Signing
If you're calling jekcms's webhook endpoints from an automation that isn't n8n itself but relays events from elsewhere, jekcms can verify an incoming X-Webhook-Signature header — an HMAC-SHA256 signature computed against a shared secret. This is a single verification layer, not a full signing/verification framework; it confirms the payload came from someone who knows the shared secret and wasn't tampered with in transit.
- A text-only post typically publishes in well under a second.
- Passing a
featured_imageURL adds time for jekcms to fetch, convert to AVIF, and store the file — expect this to take several seconds, more on slow source servers or large images. - Rate limit: 100 requests per minute per API key by default (configurable), 429 status code when exceeded.
Retry Strategy and Idempotency
Network failures are inevitable in any automated pipeline, so a retry strategy is worth building deliberately.
The jekcms webhook API is idempotent when the force_duplicate: false default is in effect: if n8n retries a failed request and the post was actually created on the first attempt, the API returns a 409 duplicate response instead of creating a second copy. This means you can safely enable n8n's built-in retry mechanism (Settings > Retry on Fail) with a small number of attempts and a delay between retries without risking duplicate content.
For image-heavy workflows where a slow source server can push response times to ten seconds or more, increase the HTTP Request node's timeout accordingly and allow a couple of retries.
The combination of duplicate prevention at the API level and automatic retries at the workflow level means your content pipeline can recover from transient failures without manual intervention. The one failure mode retries can't fix is a permanently unreachable source URL — route those to manual review instead of retrying indefinitely.
