Аналитика и интеграции · 13 / 13 · 4 мин

API и вебхуки: интеграция с вашим сайтом

Ключи API, создание задач, получение роликов и статей, подписанные вебхуки и автоматическая публикация статей на сайте.

Через API можно делать почти всё, что доступно в кабинете: создавать задачи на производство, забирать готовые ролики и статьи, добавлять карточки в план и читать тренды. Вебхуки сообщают о событиях, чтобы вашей системе не приходилось постоянно опрашивать сервис.

Ключ API

  1. Откройте «Настройки проекта → Интеграции → API-ключи».
  2. Нажмите «Создать ключ» и задайте имя: «Сайт», «CRM».
  3. Скопируйте ключ — он показывается один раз. Мы храним только его хэш.

Ключ действует только для своего проекта. Если ключ утёк, отзовите его и создайте новый. API доступен на тарифах с интеграциями; лимиты тарифа действуют и для задач, созданных через API.

Запросы

Передавайте ключ в заголовке X-Api-Key. Все ответы — JSON.

GET  /api/v1/project                 — данные проекта
POST /api/v1/jobs                    — создать задачу
GET  /api/v1/jobs/{id}               — статус задачи
GET  /api/v1/videos?status=approved  — ролики
GET  /api/v1/videos/{id}
GET  /api/v1/articles?status=approved
GET  /api/v1/articles/{id}
POST /api/v1/plan                    — добавить карточку в план
GET  /api/v1/trends?limit=20         — тренды

Пример: нарезка по ссылке

POST /api/v1/jobs
X-Api-Key: kdx_...
Content-Type: application/json

{
  "type": "clip_cut",
  "params": {
    "source": {"url": "https://example.com/webinar.mp4"},
    "count": 8, "min_sec": 20, "max_sec": 45,
    "platforms": ["youtube", "vk"]
  }
}

Ответ содержит id задачи и status: "queued". Дальше — либо опрашивайте GET /api/v1/jobs/{id}, либо подпишитесь на вебхук job.succeeded.

Вебхуки

В «Интеграции → Вебхуки» добавьте адрес и выберите события. Основные:

Событие Когда приходит
job.succeeded, job.failed Задача завершилась
video.ready_for_review Ролик готов к проверке
video.approved, video.rejected Ролик одобрен или отклонён
article.approved Статья одобрена — с полным текстом и HTML
post.published, post.failed Публикация вышла или не прошла
plan.generated Новый план готов
trend.alert Тренд выше порога

Формат доставки

Каждое событие — POST с JSON и заголовками:

  • X-Kadrix-Event — название события;
  • X-Kadrix-Delivery — идентификатор доставки;
  • X-Kadrix-Signature — sha256= и HMAC-SHA256 от тела запроса на вашем секрете.

Проверяйте подпись перед обработкой. Пример на Python:

import hmac, hashlib

def verify(secret: str, body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

Отвечайте кодом 2xx в течение 10 секунд. Если ответа нет или код другой, доставка повторяется через 1 минуту, 5 минут, 30 минут, 2 часа и 12 часов. История доставок и кнопка «Отправить тест» есть в карточке вебхука.

Статьи на сайт автоматически

Событие article.approved содержит всё, чтобы опубликовать статью без ручной работы:

  • title, slug, lang;
  • html и body_md — текст статьи;
  • meta — заголовок и описание для поисковиков;
  • ссылки на изображения;
  • ключевые слова.

Типичная схема: на сайте есть обработчик вебхука, который проверяет подпись, создаёт запись в CMS и публикует её. Одобрили статью в кабинете или в Telegram — через минуту она на сайте.

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

Передача роликов в другие сервисы

Вебхук video.approved содержит ссылку на файл, обложку и тексты для площадок. Так ролики передаются в системы, которых нет среди встроенных площадок, — например, в сервисы публикации пинов.

Безопасность

  • Храните ключи и секреты вебхуков на сервере, не в коде фронтенда.
  • Используйте HTTPS-адреса для вебхуков.
  • Делайте обработчик идемпотентным: одна и та же доставка может прийти повторно — ориентируйтесь на X-Kadrix-Delivery.

Что дальше