Універсальний вебхук для автопублікації SEO-блогу

Дії та сталі ідентифікатори

• Shopify, HubSpot, Webflow і Framer використовують підключений нативний адаптер. WordPress, OpenCart, Strapi та Lovable — встановлений конектор Blogent; v0 і Replit адаптують його до наявного застосунку. Wix, Make, n8n та власні endpoint реалізують синхронний контракт; Zapier, Albato й ApiX-Drive — callback завершення.
• inventory: передайте cursor: null і limit; відповідь — {articles: [snapshot], next_cursor: string|null}. Продовжуйте з отриманим курсором до null.
• read: передайте target та/або content_id; відповідь — {article_snapshot: snapshot}. Явний нативний target є визначальним; логічний content_id Blogent може відрізнятися від ID у CMS.
• Snapshot містить identity, title, alias, date, article, target, revision, urls і необов’язкові дані зображення/автора. article містить повний текст та SEO-поля кожної мови. Невідома первинна дата може бути null, недоступні URL — порожньою мапою.
• create: передайте статтю, унікальний operation_id, логічний content_id, порожній target та null expected_revision. Після повної публікації поверніть {posted:true,target,revision,urls}.
• update: передайте наявні target ID та актуальну expected_revision. Збережіть ID, URL/alias, первинну дату, автора й ресурси. Перевірте ревізію атомарно перед записом.

{
  "inventory_request": {"contract_version":"2.0","action":"inventory","cursor":null,"limit":10},
  "inventory_response": {"articles":[],"next_cursor":null},
  "read_request": {"contract_version":"2.0","action":"read","content_id":"logical-content-id","target":{"en":"native-42"}},
  "read_response": {"article_snapshot":{"identity":"native-42","title":"Article","alias":"article","date":null,"article":{"en":{"title":"Article","alias":"article","text":"<p>Body</p>","preview":"Summary","meta_title":"Article","meta_description":"Description"}},"target":{"en":"native-42"},"revision":"storage-revision","urls":{}}},
  "update_identity_fields": {"contract_version":"2.0","action":"update","operation_id":"new-operation-uuid","content_id":"logical-content-id","target":{"en":"native-42"},"expected_revision":"storage-revision"},
  "write_response": {"posted":true,"target":{"en":"native-42"},"revision":"new-storage-revision","urls":{}},
  "callback_body": {"contract_version":"2.0","request_id":"received-request-uuid","action":"inventory","result":{"articles":[],"next_cursor":null}}
}

Callback завершення для асинхронних сценаріїв

• Оберіть Zapier, Albato або ApiX-Drive у Blogent. Кожна дія містить request_id, точний callback_url і окремий callback_token. Передавайте ці значення через усі кроки сценарію.
• Розгалужуйте сценарій за action. Inventory/read читають CMS; create/update використовують постійний журнал операцій, транзакції та перевірку ревізії.
• Після завершення надішліть POST JSON на отриманий callback URL із заголовком Authorization: Bearer <callback_token>. Тіло: {contract_version:"2.0",request_id,action,result}. Result має формат синхронної відповіді відповідної дії.
• У разі помилки передайте result:{posted:false,message:"причина",status:409} із відповідним кодом 4xx/5xx. Часткова публікація не може повертати posted:true.
• Callback прив’язаний до запиту, дії та конфігурації. Ідентичний повтор приймається; змінений результат повертає 409, хибний токен — 401, прострочений запит — 410. Запит діє годину; Blogent може повторити його до п’яти разів із проміжком щонайменше дві хвилини. Дедуплікуйте request_id та operation_id.
• Тест відновлюється після callback: inventory → create → read → update тієї самої реальної статті. Приймання в чергу залишає стан очікування. Перевірка відбувається через захищену інтеграцію без обходу публічних сторінок.

HTML-теги, для яких потрібні стилі

Поля

• contract_version — 2.0; action задає inventory, read, create або update.
• operation_id визначає одну зміну. Збережіть хеш усього запиту та кінцеву відповідь; ідентичний повтор повертає цю відповідь.
• content_id — логічний ID Blogent; target пов’язує кожну мову з визначальним ID у CMS.
• expected_revision — null для створення та актуальна ревізія snapshot для оновлення.
• alias, мовні alias та date задаються при створенні; оновлення зберігає початкові значення CMS.
• article містить title, alias, preview HTML, text HTML, meta_title, meta_description, reading_time_minutes і toc для кожної мови.
• Необов’язкові image, image_category, rubric, params та author використовують явні мапінги CMS. Визначальним є лише ID автора поточної платформи.

Checklist приймання endpoint

1. Відхиляйте неправильну авторизацію та некоректні дії до запису.
2. Отримуйте наявні статті, повні snapshot і всі сторінки inventory без вигаданих ID чи дат.
3. Створіть і оновіть одну реальну тестову статтю зі збереженням ID, alias, дати, автора та ресурсів.
4. Перевірте повтор після перезапуску, відхилення зміненої операції та застарілої ревізії після ручної зміни.
5. Конкурентні записи та помилка будь-якої мови/зображення не повинні давати успішну відповідь.
6. Перевірте callback усіх дій: неправильні токени, змінені повтори та завершення строку дії. Обхід публічних сторінок не потрібний.

Шорткоди

Blogent може автоматично вставляти шорткод у тіло статті, щоб показувати маркетингові або інтерактивні блоки прямо всередині контенту.

Безпечний каркас PHP receiver

Каркас навмисно повертає помилку до підключення нативного адаптера CMS. Реалізуйте чотири дії, постійний журнал операцій та атомарні перевірки ревізії в handleBlogentV2(). Для асинхронного сценарію передайте той самий результат через захищений callback.

declare(strict_types=1);

function respond(int $status, array $body): never
{
    http_response_code($status);
    header('Content-Type: application/json; charset=utf-8');
    echo json_encode($body, JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES);
    exit;
}

/** Implement against the existing CMS, with authenticated inventory/read and
 * transactional create/update. Persist operation_id + canonical request hash +
 * complete result in the same commit as all locales. Replay before checking the
 * revision; compare expected_revision under a row lock/CAS. Preserve native IDs,
 * URLs, aliases, original dates, authors and assets on update. Throw on partial
 * failure. Return each action's final result, never a queue acknowledgment.
 */
function handleBlogentV2(array $command): array
{
    throw new LogicException('Connect the native CMS adapter before deployment.');
}

if (($_SERVER['REQUEST_METHOD'] ?? '') !== 'POST') respond(405, ['posted' => false, 'message' => 'POST required']);
$secret = getenv('BLOGENT_WEBHOOK_TOKEN');
$token = $_SERVER['HTTP_X_BLOGENT_TOKEN'] ?? '';
if (!is_string($secret) || strlen($secret) < 32 || !is_string($token) || !hash_equals($secret, $token)) {
    respond(401, ['posted' => false, 'message' => 'Unauthorized']);
}
if (!str_starts_with(strtolower($_SERVER['CONTENT_TYPE'] ?? ''), 'application/json')) {
    respond(415, ['posted' => false, 'message' => 'JSON required']);
}
$raw = file_get_contents('php://input');
if (!is_string($raw) || strlen($raw) > 4 * 1024 * 1024) respond(413, ['posted' => false, 'message' => 'Payload too large']);
try {
    $command = json_decode($raw, true, flags: JSON_THROW_ON_ERROR);
    if (!is_array($command) || ($command['contract_version'] ?? null) !== '2.0'
        || !in_array($command['action'] ?? null, ['inventory', 'read', 'create', 'update'], true)) {
        throw new InvalidArgumentException('Unsupported Blogent action');
    }
    // The adapter must validate action-specific fields and result completeness.
    $result = handleBlogentV2($command);
    respond(200, $result);
} catch (InvalidArgumentException | JsonException $error) {
    respond(422, ['posted' => false, 'message' => $error->getMessage()]);
} catch (Throwable $error) {
    respond(500, ['posted' => false, 'message' => 'Integration action failed']);
}