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.

Migrate to V2
On this page
  1. Implement GET, POST and PUT using the examples below.
  2. Enter the endpoint URL and secret header in your webhook settings.
  3. 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"}.

POST JSON
{
    "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.

PUT JSON
{
    "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.

GET JSON
{
    "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.

FieldTypeDescription
articleRequiredobjectComplete content by language: article.en, article.uk, etc.
aliasRequiredstringA common article key for creating it once. Use it to prevent duplicate creation.
article.*.aliasRequiredstringThe language’s URL slug, e.g. article-en. Keep it unchanged when updating; return its saved value on GET.
article.*.titleRequiredstringVisible heading.
article.*.previewRequiredstring (HTML)HTML excerpt for article listings; may be an empty string.
article.*.textRequiredstring (HTML)Full HTML: TL;DR, links, inline images, tables, video, FAQ and shortcodes.
article.*.meta_title / meta_descriptionRequiredstringSEO title and description; may be empty strings.
article.*.tocOptionalarrayTOC entries: id, title, level. Empty array means no TOC.
article.*.reading_time_minutesOptionalintegerReading time in minutes.
dateOptionalstring (date/time)Publication date; keep the original date on updates.
modified_atOptionalstring (date/time)Last update time; display it and use dateModified.
imageOptionalstring | null | falseCover URL. Save it permanently. null means no cover; false selects the explicitly configured image_category.
image_categoryOptionalstringExplicit source of your website’s images when image is false.
author_idOptionalstring | integerSelected author’s ID on your website, from the optional author list.
rubric / paramsOptionalstringConfigured category and product parameters.

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;.

Optional: authors from your website

If you want Blogent to choose an author, add GET /your-endpoint?authors=1 with the same secret header. Return existing author IDs and full names. In Blogent, load this list, select authors and add their role and a short description so the system can choose a suitable person for each topic. Creation then includes only author_id, the ID from your website. Without this endpoint, your website assigns the author itself.

GET JSON
{
    "authors": [
        {
            "id": "42",
            "name": "Olena Kovalenko"
        },
        {
            "id": "73",
            "name": "Taras Melnyk"
        }
    ]
}

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.

HTTPJSONMeaning
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.

  1. Enter your shortcode in the SEO blog settings. Blogent places it in the article during generation.
  2. The webhook stores it as received. Your website’s renderer then turns it into the corresponding block.
  3. 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.

PHP
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()]);
}

What to test before enabling publishing

  1. A wrong secret must not expose articles or change stored data.
  2. 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.
  3. 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.

You can edit the JSON. The test adds a unique suffix to aliases to avoid overwriting an existing article. Add other languages or a real author_id if needed.

Put your blog on autopilot

Connect your website and share what you know. Blogent takes it from there.