Connect your website via webhook
Blogent publishes complete articles and updates existing pages by URL. Your website displays the article, SEO metadata and the updated date, including dateModified in structured data.
On this page
- Implement GET, POST and PUT using the examples below.
- Enter the endpoint URL and secret header in your webhook settings.
- Run the test, then enable publishing.
1. Create an article: incoming POST JSON
Blogent sends this JSON to create an article. Save every supplied language. Return HTTP 200 with the article’s actual public URL only after saving: {"url":"https://site.example/blog/article-en"}.
{
"alias": "article",
"date": "2026-10-14 12:00:00",
"modified_at": "2026-10-14 12:00:00",
"image": "https://your-site.example/images/article-cover.webp",
"image_category": "",
"rubric": "guides",
"params": "topic:blog|seo;",
"article": {
"en": {
"title": "How to plan a useful blog article",
"alias": "article-en",
"preview": "<p>A practical guide to planning an article.</p>",
"meta_title": "Plan a useful blog article",
"meta_description": "Learn how to plan article structure and choose useful examples.",
"reading_time_minutes": 1,
"toc": [
{
"id": "main-section",
"title": "Plan the structure",
"level": 2
},
{
"id": "nested-point",
"title": "Choose useful examples",
"level": 3
}
],
"text": "<div class=\"blgn-article\"><p class=\"blgn-tldr\"><strong>TLDR:</strong> Plan the structure before writing and keep the advice practical.</p><h2 id=\"main-section\">Plan the structure</h2><p>Start with the reader’s question and a clear answer.</p><h3 id=\"nested-point\">Choose useful examples</h3><p>Use examples from your actual workflow.</p><img src=\"https://your-site.example/images/article-example.webp\" alt=\"Example article outline\" loading=\"lazy\"><p><a href=\"https://your-site.example/guides\" rel=\"noopener\" target=\"_blank\">More guides</a></p></div>"
}
},
"author_id": "42"
}2. Update an article: incoming PUT JSON
Find the article by the exact public url. Replace the supplied content in every language and return the same URL. Keep existing slugs, translation links, publication date, cover, author, category and product parameters. Save modified_at, show the updated date on the page and set dateModified in its structured data.
{
"url": "https://your-site.example/blog/article-en",
"modified_at": "2026-10-15 09:00:00",
"article": {
"en": {
"title": "How to plan a useful blog article",
"preview": "<p>A practical guide to planning an article.</p>",
"meta_title": "Plan a useful blog article",
"meta_description": "Updated advice on article structure, examples and review.",
"reading_time_minutes": 1,
"toc": [
{
"id": "main-section",
"title": "Plan the structure",
"level": 2
},
{
"id": "nested-point",
"title": "Choose useful examples",
"level": 3
}
],
"text": "<div class=\"blgn-article\"><p class=\"blgn-tldr\"><strong>TLDR:</strong> Keep a clear structure and update the advice when your process changes.</p><h2 id=\"main-section\">Plan the structure</h2><p>Start with the reader’s question and a clear answer.</p><h3 id=\"nested-point\">Choose useful examples</h3><p>Use examples from your actual workflow.</p><img src=\"https://your-site.example/images/article-example.webp\" alt=\"Example article outline\" loading=\"lazy\"><p><a href=\"https://your-site.example/guides\" rel=\"noopener\" target=\"_blank\">More guides</a></p></div>"
}
}
}3. Return the current article when Blogent requests it
Blogent sends GET /your-endpoint?url=https%3A%2F%2Fsite.example%2Fblog%2Farticle-en. Find this page and return {"article":{...}} with every saved language, as below. This lets Blogent work with the current text and verify a saved update. No other top-level fields are needed.
{
"article": {
"en": {
"title": "How to plan a useful blog article",
"alias": "article-en",
"preview": "<p>A practical guide to planning an article.</p>",
"meta_title": "Plan a useful blog article",
"meta_description": "Learn how to plan article structure and choose useful examples.",
"reading_time_minutes": 1,
"toc": [
{
"id": "main-section",
"title": "Plan the structure",
"level": 2
},
{
"id": "nested-point",
"title": "Choose useful examples",
"level": 3
}
],
"text": "<div class=\"blgn-article\"><p class=\"blgn-tldr\"><strong>TLDR:</strong> Plan the structure before writing and keep the advice practical.</p><h2 id=\"main-section\">Plan the structure</h2><p>Start with the reader’s question and a clear answer.</p><h3 id=\"nested-point\">Choose useful examples</h3><p>Use examples from your actual workflow.</p><img src=\"https://your-site.example/images/article-example.webp\" alt=\"Example article outline\" loading=\"lazy\"><p><a href=\"https://your-site.example/guides\" rel=\"noopener\" target=\"_blank\">More guides</a></p></div>"
}
}
}Which fields to handle
“Required” means the field must be present. “Optional” means save it when supplied. “—” means it is not sent. Handle every language in article, using your website’s own translation routes.
| Field | Type | Description |
|---|---|---|
articleRequired | object | Complete content by language: article.en, article.uk, etc. |
aliasRequired | string | A common article key for creating it once. Use it to prevent duplicate creation. |
article.*.aliasRequired | string | The language’s URL slug, e.g. article-en. Keep it unchanged when updating; return its saved value on GET. |
article.*.titleRequired | string | Visible heading. |
article.*.previewRequired | string (HTML) | HTML excerpt for article listings; may be an empty string. |
article.*.textRequired | string (HTML) | Full HTML: TL;DR, links, inline images, tables, video, FAQ and shortcodes. |
article.*.meta_title / meta_descriptionRequired | string | SEO title and description; may be empty strings. |
article.*.tocOptional | array | TOC entries: id, title, level. Empty array means no TOC. |
article.*.reading_time_minutesOptional | integer | Reading time in minutes. |
dateOptional | string (date/time) | Publication date; keep the original date on updates. |
modified_atOptional | string (date/time) | Last update time; display it and use dateModified. |
imageOptional | string | null | false | Cover URL. Save it permanently. null means no cover; false selects the explicitly configured image_category. |
image_categoryOptional | string | Explicit source of your website’s images when image is false. |
author_idOptional | string | integer | Selected author’s ID on your website, from the optional author list. |
rubric / paramsOptional | string | Configured category and product parameters. |
| Field | Type | Description |
|---|---|---|
articleRequired | object | Complete content by language: article.en, article.uk, etc. |
urlRequired | string | Full public URL used to find the article. GET sends it in the query; updates put it first in JSON. |
article.*.titleRequired | string | Visible heading. |
article.*.previewRequired | string (HTML) | HTML excerpt for article listings; may be an empty string. |
article.*.textRequired | string (HTML) | Full HTML: TL;DR, links, inline images, tables, video, FAQ and shortcodes. |
article.*.meta_title / meta_descriptionRequired | string | SEO title and description; may be empty strings. |
article.*.tocOptional | array | TOC entries: id, title, level. Empty array means no TOC. |
article.*.reading_time_minutesOptional | integer | Reading time in minutes. |
modified_atOptional | string (date/time) | Last update time; display it and use dateModified. |
| Field | Type | Description |
|---|---|---|
articleRequired | object | Complete content by language: article.en, article.uk, etc. |
article.*.aliasRequired | string | The language’s URL slug, e.g. article-en. Keep it unchanged when updating; return its saved value on GET. |
article.*.titleRequired | string | Visible heading. |
article.*.previewRequired | string (HTML) | HTML excerpt for article listings; may be an empty string. |
article.*.textRequired | string (HTML) | Full HTML: TL;DR, links, inline images, tables, video, FAQ and shortcodes. |
article.*.meta_title / meta_descriptionRequired | string | SEO title and description; may be empty strings. |
article.*.tocOptional | array | TOC entries: id, title, level. Empty array means no TOC. |
article.*.reading_time_minutesOptional | integer | Reading time in minutes. |
If you use params, store the supplied attributes for your catalog filters or recommendations. Keep the syntax configured for your website; for example, key:value1|value2;.
Responses and errors
Return JSON with Content-Type: application/json. A successful POST or PUT returns the public URL; a successful GET returns article or authors. Do not confirm success before all supplied languages are saved.
| HTTP | JSON | Meaning |
|---|---|---|
| 200 POST / PUT | {"url":"https://site.example/blog/article-en"} | Saved article; return its actual URL. |
| 200 GET | {"article":{...}} / {"authors":[...]} | Saved article or author list. |
| 500 | {"error":"Article not found at the requested URL"} | Any failure: explain the specific cause in error. |
Display the article on your website
Blogent sends ready-to-publish HTML. Store it without rewriting. Style the article in your website template.
The wrapper is .blgn-article; its TL;DR summary is p.blgn-tldr inside text. Media use .blgn-media, .blgn-image, .blgn-video; shortcode blocks use .blgn-shortcode.
Support headings h1–h4, paragraphs, lists, links, images, tables, blockquotes, code, iframe/video and FAQ blocks with details/summary. Keep heading IDs, media attributes, link rel/target and responsive wrappers.
Display toc as links to the heading IDs in text, and reading_time_minutes as reading time. Use meta_title/meta_description in page metadata.
Show the updated date on the article page and set dateModified in structured data. Keep the original publication date as datePublished.
Forms and other blocks inside articles
If your website uses shortcodes, you can include a form, banner or product block in an article.
- Enter your shortcode in the SEO blog settings. Blogent places it in the article during generation.
- The webhook stores it as received. Your website’s renderer then turns it into the corresponding block.
- Use the exact shortcode name and parameters supported by your site.
- Call to action:
[cta] - Promo code:
[promo_code] - Contact form:
[contact-form] - Product slider:
[products_slider category="chairs"] - Featured products:
[featured_products] - Banner or information block:
[info_banner]
These names are examples. If your site does not recognize a shortcode, add support in its renderer before using it.
Handler examples
Choose your server language. These examples handle HTTP requests and authentication; connect the marked read/save functions to your existing article storage. They deliberately fail until those functions are implemented. The authors branch is optional.
declare(strict_types=1);
// Connect these functions to your website's existing article storage.
function listAuthors(): array
{
// Optional: return ['authors' => [['id' => '42', 'name' => 'Full Name']]] from your site.
throw new DomainException('Author list is not implemented');
}
function readArticle(string $url): array
{
// Find by the exact public URL and return the saved article fields.
// Return ['article' => $savedLanguages] including aliases and all supplied article fields.
// If the article does not exist, throw an error explaining the cause.
throw new LogicException('Connect the website article read here.');
}
function saveArticle(array $data, string $method): array
{
// POST: create. PUT: update the page identified by url; never create another.
// Save all supplied languages and return ['url' => $publicUrl].
// On update, keep the URL, original date, author and existing images.
// Repeated creation with the same alias must not create a duplicate.
throw new LogicException('Connect the website article save here.');
}
header('Content-Type: application/json; charset=utf-8');
$secret = getenv('BLOG_WEBHOOK_TOKEN');
$token = $_SERVER['HTTP_X_WEBHOOK_TOKEN'] ?? '';
if (!is_string($secret) || strlen($secret) < 32 || !hash_equals($secret, $token)) {
http_response_code(500);
echo json_encode(['error' => 'Unauthorized']);
exit;
}
try {
$method = $_SERVER['REQUEST_METHOD'] ?? '';
if ($method === 'GET') {
$url = $_GET['url'] ?? null;
if (($_GET['authors'] ?? '') !== '1' && (!is_string($url) || !filter_var($url, FILTER_VALIDATE_URL))) throw new InvalidArgumentException('Public URL required');
$result = ($_GET['authors'] ?? '') === '1' ? listAuthors() : readArticle($url);
} elseif ($method === 'POST' || $method === 'PUT') {
if (!str_starts_with(strtolower($_SERVER['CONTENT_TYPE'] ?? ''), 'application/json')) throw new InvalidArgumentException('JSON required');
$body = file_get_contents('php://input');
if (!is_string($body) || strlen($body) > 4 * 1024 * 1024) throw new InvalidArgumentException('Payload too large');
$data = json_decode($body, true, flags: JSON_THROW_ON_ERROR);
if (!is_array($data) || !is_array($data['article'] ?? null) || $data['article'] === []) throw new InvalidArgumentException('Article required');
if ($method === 'PUT' && (!is_string($data['url'] ?? null) || !filter_var($data['url'], FILTER_VALIDATE_URL))) throw new InvalidArgumentException('Public URL required for PUT');
if ($method === 'POST' && array_key_exists('url', $data)) throw new InvalidArgumentException('POST creates articles; use PUT to update');
$result = saveArticle($data, $method);
} else {
http_response_code(500);
header('Allow: GET, POST, PUT');
echo json_encode(['error' => 'GET, POST or PUT required']);
exit;
}
echo json_encode($result, JSON_THROW_ON_ERROR);
} catch (Throwable $error) {
http_response_code(500);
echo json_encode(['error' => $error->getMessage()]);
}import { createServer } from 'node:http';
import { timingSafeEqual } from 'node:crypto';
// Connect these functions to your existing website storage.
async function readArticle(url) {
// Find by the exact public URL; return { article: savedLanguages }.
// Include saved aliases and every supplied article field. Missing page: throw an error with the cause.
throw new Error('Connect your article reader');
}
async function saveArticle(data, method) {
// POST: create. PUT: update the page identified by url; missing page: throw an error with the cause.
// Save every supplied language, then return { url: actualPublicUrl }.
// Keep slugs, original date, author, cover and translations on updates.
// Save modified_at and display it on the page and in dateModified.
// Repeated create with the same alias must not create a duplicate.
throw new Error('Connect your article writer');
}
async function listAuthors() {
// Optional: return { authors: [{ id: '42', name: 'Full Name' }] } from your site.
throw new Error('Author list is not implemented');
}
const secret = process.env.BLOG_WEBHOOK_TOKEN;
if (!secret || secret.length < 32) throw new Error('Configure BLOG_WEBHOOK_TOKEN');
const fail = message => { throw new Error(message); };
const publicUrl = value => {
try { return typeof value === 'string' && ['http:', 'https:'].includes(new URL(value).protocol); }
catch { return false; }
};
createServer(async (req, res) => {
const respond = (status, body) => {
res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
res.end(JSON.stringify(body));
};
const token = Buffer.from(req.headers['x-webhook-token'] || '');
const expected = Buffer.from(secret);
if (token.length !== expected.length || !timingSafeEqual(token, expected)) return respond(500, { error: 'Unauthorized' });
try {
const query = new URL(req.url, 'http://localhost').searchParams;
let result;
if (req.method === 'GET') {
if (query.get('authors') === '1') result = await listAuthors();
else {
if (!publicUrl(query.get('url'))) fail('Public URL required');
result = await readArticle(query.get('url'));
}
} else if (req.method === 'POST' || req.method === 'PUT') {
if (!(req.headers['content-type'] || '').startsWith('application/json')) fail('JSON required');
const chunks = []; let size = 0;
for await (const chunk of req) {
size += chunk.length;
if (size > 4 * 1024 * 1024) fail('Payload too large');
chunks.push(chunk);
}
let data;
try { data = JSON.parse(Buffer.concat(chunks).toString()); }
catch { fail('Invalid JSON'); }
if (!data?.article || typeof data.article !== 'object' || Array.isArray(data.article) || !Object.keys(data.article).length) fail('Article required');
if (req.method === 'PUT' && !publicUrl(data.url)) fail('Public URL required for PUT');
if (req.method === 'POST' && 'url' in data) fail('POST creates articles; use PUT to update');
result = await saveArticle(data, req.method);
} else {
res.setHeader('Allow', 'GET, POST, PUT');
return respond(500, { error: 'GET, POST or PUT required' });
}
respond(200, result);
} catch (error) {
respond(500, { error: error.message });
}
}).listen(process.env.PORT || 3000);
import hmac
import json
import os
from http.server import BaseHTTPRequestHandler, HTTPServer
from urllib.parse import parse_qs, urlparse
# Connect these functions to your existing website storage.
def read_article(url):
# Find by exact public URL; return {"article": saved_languages}.
# Include saved aliases and every supplied article field. Missing page: raise an error with the cause.
raise NotImplementedError("Connect your article reader")
def save_article(data, method):
# POST: create. PUT: update the page identified by url; missing page: raise an error with the cause.
# Save every language, then return {"url": actual_public_url}.
# Keep slugs, original date, author, cover and translations on updates.
# Save modified_at and show it on the page and in dateModified.
# Repeated create with the same alias must not create a duplicate.
raise NotImplementedError("Connect your article writer")
def list_authors():
# Optional: return {"authors": [{"id": "42", "name": "Full Name"}]} from your site.
raise RequestError("Author list is not implemented")
class RequestError(Exception):
pass
secret = os.environ.get("BLOG_WEBHOOK_TOKEN", "")
if len(secret) < 32:
raise RuntimeError("Configure BLOG_WEBHOOK_TOKEN")
def public_url(value):
if not isinstance(value, str):
return False
parsed = urlparse(value)
return parsed.scheme in ("http", "https") and bool(parsed.netloc)
class Handler(BaseHTTPRequestHandler):
def respond(self, status, body):
self.send_response(status)
self.send_header("Content-Type", "application/json; charset=utf-8")
self.end_headers()
self.wfile.write(json.dumps(body, ensure_ascii=False).encode())
def handle_request(self):
if not hmac.compare_digest(secret.encode(), self.headers.get("X-Webhook-Token", "").encode()):
return self.respond(500, {"error": "Unauthorized"})
try:
if self.command == "GET":
query = parse_qs(urlparse(self.path).query)
if query.get("authors") == ["1"]:
result = list_authors()
else:
url = query.get("url", [None])[0]
if not public_url(url):
raise RequestError("Public URL required")
result = read_article(url)
else:
if not self.headers.get("Content-Type", "").startswith("application/json"):
raise RequestError("JSON required")
size = int(self.headers.get("Content-Length", "0"))
if size < 1 or size > 4 * 1024 * 1024:
raise RequestError("Invalid payload size")
data = json.loads(self.rfile.read(size))
if not isinstance(data, dict) or not isinstance(data.get("article"), dict) or not data["article"]:
raise RequestError("Article required")
if self.command == "PUT" and not public_url(data.get("url")):
raise RequestError("Public URL required for PUT")
if self.command == "POST" and "url" in data:
raise RequestError("POST creates articles; use PUT to update")
result = save_article(data, self.command)
self.respond(200, result)
except Exception as error:
self.respond(500, {"error": str(error)})
def send_error(self, code, message=None, explain=None):
self.respond(500, {"error": message or "Request could not be processed"})
do_GET = handle_request
do_POST = handle_request
do_PUT = handle_request
HTTPServer(("127.0.0.1", int(os.environ.get("PORT", "3000"))), Handler).serve_forever()
What to test before enabling publishing
- A wrong secret must not expose articles or change stored data.
- Create, read, update and read the same article in every supplied language. Compare full HTML, TL;DR, inline images, preview, SEO fields, TOC and reading time. Check that the URL, original publication date, cover and author stay unchanged and no duplicate appears.
- On the page, check heading links, media, meta tags and the visible updated date. Check dateModified in structured data.
Test your connection
The test creates one article, reads it, updates it and reads it again. It compares every supplied language, full HTML, SEO fields, TOC and reading time. It leaves the test article on your website.
Similar integrations
Put your blog on autopilot
Connect your website and share what you know. Blogent takes it from there.