Подключение через
Claude/Codex

Когда нужен этот сценарий

Этот сценарий подходит, когда вы не хотите писать webhook-обработчик вручную, а хотите поручить задачу Claude, Codex, Cursor Agent, Lovable или другому AI, который уже работает в кодовой базе.

В интерфейсе SeoSmith этот путь соответствует карточке «Вайбкод» в разделе интеграций, но по сути это сценарий подключения через AI-ассистента.

Какой минимальный контракт нужно сообщить AI

Безопасно раскрывать ИИ только эти части интеграции:

• путь endpoint: /api/seosmith;
• метод: POST;
• заголовок подписи: X-SeoSmith-Signature: sha256=<hmac-hex>;
• тип подписи: HMAC-SHA256 от raw body;
• секрет хранится в SEOSMITH_WEBHOOK_SECRET;
• payload содержит event, article и company.

Этого достаточно, чтобы AI корректно собрал endpoint в проекте клиента.

Готовый prompt для Claude/Codex

Ниже prompt, который можно дать Claude, Codex, Cursor Agent, Lovable или другому AI, работающему прямо в кодовой базе:

В моём проекте нужен серверный endpoint для приёма webhook-запросов от сервиса SeoSmith.

Добавь POST-роут по пути /api/seosmith, используя текущий стек, роутинг, ORM и паттерны проекта. Не создавай новый отдельный микросервис, если в проекте уже есть backend или server routes.

Webhook получает:
- Заголовок X-SeoSmith-Signature со значением вида sha256=<hmac-hex>
- JSON body вида:
  {
    "event": "article.published",
    "article": {
      "id": 123,
      "title": "...",
      "slug": "...",
      "url": "...",
      "body": "<p>...готовый HTML...</p>",
      "meta": { "title": "...", "description": "...", "keywords": ["..."] },
      "faq": [{ "q": "...", "a": "..." }],
      "json_ld": "{...}",
      "image_prompt": "...",
      "alt_text": "..."
    },
    "company": {
      "name": "...",
      "site_url": "https://example.com"
    }
  }

Реализуй логику:
1. Прочитай тело как raw text или raw bytes ДО JSON.parse
2. Вычисли HMAC-SHA256 от raw body с ключом из env-переменной SEOSMITH_WEBHOOK_SECRET
3. Сравни с подписью из X-SeoSmith-Signature через безопасное compare, а не через обычный ==
4. Если подпись невалидна — верни 401
5. Если event не article.published — верни 200 JSON { ok: true, skipped: true }
6. Если event корректный — сохрани статью в уже существующую модель/таблицу/коллекцию публикаций проекта
7. Сохрани минимум поля: title, slug, body_html, meta_title, meta_description, meta_keywords, faq, json_ld
8. Верни 200 JSON { ok: true }

Ограничения безопасности:
- Не хардкодь никакие секреты
- Не отключай проверку подписи даже временно
- Не логируй полное значение SEOSMITH_WEBHOOK_SECRET
- Не принимай GET/PUT вместо POST
- Не делай endpoint публичной формой импорта без проверки подписи
- Не заменяй безопасное сравнение подписи на обычное ==

В конце:
1. Покажи полный URL endpoint, который получится после деплоя
2. Объясни, куда добавить SEOSMITH_WEBHOOK_SECRET локально и на сервере
3. Скажи, что после добавления env нужно перезапустить приложение или контейнер
4. Дай короткую инструкцию по проверке endpoint после деплоя

Prompt для второй итерации, если AI пошел не туда

Если инструмент начал придумывать новый data model, собственный CMS или странную схему публикации, используйте уточняющий prompt:

Не изобретай новую архитектуру. Встрой webhook в уже существующую систему публикаций проекта.

Сначала найди:
- где в проекте уже хранятся публичные статьи, блог-посты или страницы
- какой route pattern используется для публикаций
- какая ORM-модель или таблица отвечает за контент

После этого:
- используй существующую модель публикаций, если она подходит
- если модель отличается, добавь только минимальные поля для webhook-импорта
- не трогай клиентские страницы без необходимости
- не добавляй админку, если её нет

Если не можешь однозначно определить существующую модель хранения статей — не импровизируй, а задай мне конкретный вопрос по текущей структуре проекта.

Куда сохранять статью

Это зависит от архитектуры проекта. Универсального ответа нет, поэтому AI должен встроиться в уже существующую контентную модель или файловую структуру, а не изобретать новую CMS.

Безопасная структура обработчика

Хороший AI-результат должен стремиться к такой структуре:

Что AI не должен делать

• Хардкодить SEOSMITH_WEBHOOK_SECRET в код, примеры или commit.
• Логировать полный raw payload вместе с секретом или подписью.
• Сохранять статью без проверки подписи «на время дебага».
• Делать endpoint доступным для любого JSON без HMAC-проверки.
• Менять основной контентный pipeline проекта, если достаточно добавить один route.
• Создавать отдельную таблицу для статьи, если в проекте уже есть blog/posts/pages.

Какие поля действительно важны для сохранения

Даже если проект хранит статьи в своей форме, AI должен постараться не потерять эти данные из webhook:

• title и slug;
• body как готовый HTML;
• meta.title и meta.description;
• meta.keywords;
• faq;
• json_ld.

image_prompt и alt_text можно хранить как дополнительные поля или метаданные, если проект реально будет их использовать.

Как объяснить AI деплой и проверку

После генерации кода AI должен не только написать route, но и выдать понятный план запуска:

1. как задеплоить изменения;
2. куда добавить SEOSMITH_WEBHOOK_SECRET локально и на сервере;
3. что приложение нужно перезапустить после изменения env;
4. какой конечный URL endpoint нужно вставить в SeoSmith.

Финальная проверка перед сохранением коннектора

• Endpoint существует по HTTPS.
• Он принимает только POST.
• В коде есть HMAC-SHA256 по raw body.
• Используется безопасное compare для подписи.
• Секрет читается из env, а не хранится в коде.
• Есть понятная точка сохранения статьи в структуру проекта клиента.