Webhook API
для кросспостинга

Базовая информация

• Base URL: https://wh.crosslybot.ru
• Метод: POST
• Path: /v1/webhooks/{slug}
• Аутентификация: Bearer-токен в заголовке Authorization
• Content-Type: application/json
• Кодировка: UTF-8
• Размер запроса: до 5 МБ

HTTP-заголовки запроса

Поля JSON payload

Минимальный валидный пост: должен содержать хотя бы одно из text, media[] или buttons[].

Лимиты и валидация медиа

HTTP-коды ответов

Decisions в «Истории запросов»

В UI карточки endpoint'а есть журнал последних 100 запросов. Каждая запись содержит decision — внутренняя причина решения. Это поможет отладить интеграцию когда клиент видит просто 401 или 429:

Примеры кода

Замените 8qwv9XeTcR6Nyn2nlIW_wQ на свой slug (копируется из карточки в /channels) и crossly_live_... на ваш токен.

curl -X POST https://wh.crosslybot.ru/v1/webhooks/8qwv9XeTcR6Nyn2nlIW_wQ \
  -H "Authorization: Bearer crossly_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "text": "Привет, мир!",
    "entities": [{"type": "bold", "offset": 0, "length": 6}],
    "media": [
      {"type": "photo", "url": "https://cdn.example.com/img.jpg"}
    ],
    "external_id": "post-123",
    "metadata": {"source": "ai-agent"}
  }'

import os, time, uuid, requests
from requests.adapters import HTTPAdapter
from urllib3.util import Retry

session = requests.Session()
session.mount("https://", HTTPAdapter(max_retries=Retry(
    total=4,
    backoff_factor=2,            # 2с / 4с / 8с / 16с
    status_forcelist=[429, 500, 502, 503, 504],
    allowed_methods=["POST"],
    respect_retry_after_header=True,
)))

SLUG = "8qwv9XeTcR6Nyn2nlIW_wQ"
TOKEN = os.environ["CROSSLY_TOKEN"]

resp = session.post(
    f"https://wh.crosslybot.ru/v1/webhooks/{SLUG}",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
        "User-Agent": "my-ai-agent/1.0",
    },
    json={
        "text": "Привет, мир!",
        "entities": [{"type": "bold", "offset": 0, "length": 6}],
        "media": [{"type": "photo", "url": "https://cdn.example.com/img.jpg"}],
        "external_id": "post-123",
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

import { randomUUID } from "crypto";

const SLUG = "8qwv9XeTcR6Nyn2nlIW_wQ";
const TOKEN = process.env.CROSSLY_TOKEN;
const BACKOFFS = [2000, 4000, 8000, 16000]; // 2c / 4с / 8с / 16с

async function publish(payload) {
  for (let attempt = 0; attempt < BACKOFFS.length + 1; attempt++) {
    const resp = await fetch(
      `https://wh.crosslybot.ru/v1/webhooks/${SLUG}`,
      {
        method: "POST",
        headers: {
          "Authorization": `Bearer ${TOKEN}`,
          "Content-Type": "application/json",
          "Idempotency-Key": randomUUID(),
          "User-Agent": "my-ai-agent/1.0",
        },
        body: JSON.stringify(payload),
      }
    );
    if (resp.ok) return resp.json();
    if (![429, 500, 502, 503, 504].includes(resp.status)) {
      throw new Error(`Crosslybot ${resp.status}: ${await resp.text()}`);
    }
    if (attempt === BACKOFFS.length) throw new Error("Max retries exceeded");
    const ra = Number(resp.headers.get("retry-after")) * 1000;
    await new Promise(r => setTimeout(r, ra || BACKOFFS[attempt]));
  }
}

await publish({
  text: "Привет, мир!",
  media: [{ type: "photo", url: "https://cdn.example.com/img.jpg" }],
  external_id: "post-123",
});

Sandbox: тестирование без публикации

Sandbox — отдельный эндпоинт для проверки формата payload и валидации медиа без записи в БД и без публикации в каналы. Ответ совпадает по структуре с боевым: видно какие ошибки, какие цели получили бы пост, какая обрезка текста применилась бы под каждую платформу.

curl -X POST https://wh.crosslybot.ru/v1/sandbox/test \\
  -H "Authorization: Bearer crossly_test_xxxxxxxxxxxxxxxxxxxx" \\
  -H "Content-Type: application/json" \\
  -d '{
    "text": "Тестовый пост",
    "entities": [{"type": "bold", "offset": 0, "length": 8}],
    "media": [
      {"type": "photo", "url": "https://cdn.example.com/img.jpg"}
    ]
  }'

{
  "ok": true,
  "would_create_post": true,
  "validation": {
    "schema": "passed",
    "media": [{"url": "https://cdn.example.com/img.jpg", "size_mb": 2.4, "ok": true}],
    "entities": "passed"
  },
  "preview": {
    "telegram": {"text_after_trim": "Тестовый пост", "trimmed_chars": 0},
    "vk":       {"text_after_trim": "Тестовый пост", "trimmed_chars": 0},
    "max":      {"text_after_trim": "Тестовый пост", "trimmed_chars": 0}
  }
}

💡 Используйте sandbox в CI/CD как smoke-тест после каждого деплоя интеграции — это бесплатный способ убедиться что payload-генератор не сломан.

Совместимость с Telegram Bot API

Формат payload максимально близок к Telegram Bot API — если у вас уже есть код для TG, большую часть можно переиспользовать. Но есть отличия в моделях, перечислены ниже.

💡 Если переносите код с TG Bot API: основная адаптация — собирайте альбом в один POST с media[] вместо последовательных send'ов. Entities и URL-кнопки переиспользуются как есть.

Адресная публикация и отложенные паузы

Три независимых механизма управления публикацией прямо из payload — комбинируйте их свободно.

1. Адресная публикация — targets[]

По умолчанию пост идёт во все активные цели проекта. Чтобы ограничить — передайте targets[] с public_id целей (копируется из карточки цели).

{
  "text": "Анонс — только в основные каналы",
  "targets": [
    { "id": "tgt_aBcDeFgHiJkLmNoPqRsTuV" },
    { "id": "tgt_xYz123456789abcdefGhi" }
  ]
}

⚠️ Если ни один из переданных id не совпал с целями проекта — ответ 422 invalid_targets, пост не создаётся.

2. Автопауза проекта — ad_pause_minutes

После первой успешной публикации поста весь проект ставится на паузу на N минут. Применяется один раз — повторные post-target'ы того же поста (multi-target) паузу не продлевают.

{
  "text": "Рекламная вставка",
  "is_advertisement": true,
  "ad_pause_minutes": 60
}

3. Автопауза канала — ad_target_pause_minutes

Каждый успешно опубликованный канал ставится на глобальную паузу — действует во всех ваших проектах с этим каналом. Удобно когда контракт с площадкой требует «не больше одной рекламы в час»: параллельный обычный кросспостинг в этот канал тоже подождёт.

{
  "text": "Реклама в TG-канал на 24 часа",
  "is_advertisement": true,
  "ad_target_pause_minutes": 1440,
  "targets": [
    { "id": "tgt_aBcDeFgHiJkLmNoPqRsTuV" }
  ]
}

• • Поля ad_pause_minutes и ad_target_pause_minutes независимы — можно одно, оба или ни одного.
• • Триггер автопаузы — фактическая успешная публикация. Если все цели упали — пауза не применяется.
• • Пауза цели — глобальная на канал: действует во всех ваших проектах, где этот канал используется. Параллельный обычный кросспостинг в тот же канал тоже подождёт.
• • Существующая ручная пауза не сокращается. Авто-пауза только продлевает, если новая позже.
• • is_advertisement — метка для статистики, не обязательна для работы пауз.

Пауза без публикации — temp-pause / temp-resume

Автопаузы выше срабатывают вместе с публикацией поста. Если нужно поставить паузу отдельно (например рекламная площадка хочет «забронировать тишину» наперёд) — есть два endpoint'а, которые ничего не публикуют, только управляют паузой.

POST /v1/webhooks/{slug}/temp-pause

{
  "project_minutes": 60,        // пауза всего проекта (опционально)
  "target_minutes": 120,        // глобальная пауза каналов (опционально)
  "targets": ["tgt_aBc..."]     // какие каналы; пусто = все цели проекта
}

• • Минимум одно из project_minutes / target_minutes должно быть > 0.
• • target_minutes — глобальная пауза ресурса: действует во всех ваших проектах с этим каналом.
• • Если targets указан, но ни один id не принадлежит проектам этого webhook'а — 422 invalid_targets.
• • Идемпотентно: не сокращает уже активную более длинную паузу.

POST /v1/webhooks/{slug}/temp-resume

{
  "scope": "all",               // "project" | "targets" | "all" (default all)
  "targets": ["tgt_aBc..."]     // какие каналы снять (если scope=targets)
}

Накопленные за время паузы посты публикуются с интервалом 1 мин после снятия. Оба endpoint'а используют тот же auth-стек (Bearer + опциональный HMAC + timestamp), что и публикация.

Ответ: {ok, request_id, projects_affected, resources_affected, rescheduled_post_targets}.

Discovery endpoint — для MCP и автоматизаций

Чтобы MCP-серверам (Claude Desktop, Cursor) и скриптам не приходилось вручную копировать tgt_… каждой цели и знание о платформах — есть один запрос, который отдаёт всю структуру:

curl https://wh.crosslybot.ru/v1/webhooks/{slug}/info \
  -H "Authorization: Bearer crossly_live_..."

Ответ (режим по умолчанию — обезличенный):

{
  "endpoint": { "slug": "...", "name": null, "verbose": false },
  "projects": [
    {
      "index": 1,
      "name": null,
      "paused_until": null,
      "targets": [
        { "id": "tgt_aBc...", "platform": "telegram", "name": null, "paused_until": null },
        { "id": "tgt_xYz...", "platform": "max", "name": null, "paused_until": null }
      ]
    }
  ],
  "capabilities": {
    "entity_types": ["bold","italic","spoiler", ...],
    "media_types": ["photo","video","audio"],
    "limits": {
      "max_text_length": 15895, "max_media": 10,
      "max_buttons_rows": 8, "max_buttons_per_row": 8,
      "max_payload_bytes": 5242880, "max_pause_minutes": 1440
    }
  }
}

Verbose режим — включается в карточке webhook IN (раздел «Безопасность» → toggle «Раскрывать имена в discovery (/info)»). Тогда в ответе вместо null появятся реальные названия проекта, целей и самого endpoint'а.

• • Безопасность идентична POST: те же Bearer, IP allowlist, timestamp, HMAC (для GET подписывается method\npath\ntimestamp вместо body), tariff guard.
• • Отдельный rate-limit 60 запросов/мин — не съедает publishing budget. Violations пишутся в общий счётчик soft-block, атакующий не может через flood /info обойти автозащиту.
• • paused_until для проекта и цели всегда видим — клиент знает что пост встанет в очередь, не публикуется сразу.
• • capabilities.limits — клиент-валидатор может проверить текст/медиа/паузы до отправки и избежать 422.

⚠️ Не возвращаем точные значения rate-limit (min_interval, hourly_quota) — раскрытие даёт атакующему с украденным токеном protocol cheatsheet.

Hosted-вариант (рекомендуется) — никаких локальных установок, только URL в конфиге AI-клиента:

// claude_desktop_config.json
{
  "mcpServers": {
    "crosslybot": {
      "url": "https://mcp.crosslybot.ru/sse/{slug}",
      "headers": {
        "Authorization": "Bearer crossly_live_..."
      }
    }
  }
}

Слаг и токен — из карточки webhook IN в личном кабинете. Включите toggle «Раскрывать имена в discovery (/info)» чтобы AI мог находить цели по именам.

Tools AI получает автоматически:

• • crosslybot_discover — список ваших проектов и целей публикации (Telegram/VK/Max).
• • crosslybot_publish — публикация поста. Принимает tgt_… или имя цели ("маркетинг"). Поддерживает все поля payload включая автопаузу проекта/цели после публикации.

С HMAC-защитой — добавьте ещё один header:

"headers": {
  "Authorization": "Bearer crossly_live_...",
  "X-Crosslybot-Hmac-Secret": "..."
}

⚠️ Если включён IP allowlist, добавьте в whitelist IP нашего MCP-сервера: 89.223.125.61.

Self-hosted доступен через Docker (multi-arch) — см. GitHub или образ ghcr.io/antiblef/crosslybot-mcp. Документация: /mcp.

Идемпотентность

Заголовок Idempotency-Key или поле external_id в payload — стандартный способ безопасных повторов запросов.

• • Ключи кешируются на 24 часа в рамках endpoint
• • Повторный POST с тем же ключом возвращает 202 и закэшированный ответ — БЕЗ создания дубликата поста
• • Если первый запрос упал на 5xx и не был обработан — повтор создаст пост впервые
• • Длина ключа до 128 символов. Рекомендуется UUIDv4 (универсально) или бизнес-ID (стабильно для логики)

Политика повторов (для клиентов)

Когда повторять запрос, и через какое время.

⚠ ВАЖНО: при retry используйте тот же Idempotency-Key — иначе создастся дубликат поста.

Rate limit и квоты

Четырёхуровневая защита per-slot: настраиваемый интервал + burst + часовая квота по тарифу + автопауза при систематических нарушениях. Превышение → 429 Too Many Requests с заголовком Retry-After.

• • Per-slot изоляция: лимиты привязаны к URL входящего webhook'а (slug), а не к аккаунту — атака на один webhook не задевает другие.
• • Min-interval: «не чаще одного запроса в N секунд», настраивается в карточке endpoint'а (по умолчанию 10s). Защита от случайного флуда из-за бага в bot'е/скрипте отправителя.
• • Burst: sliding window 1 секунда. Защита от мгновенного флуда.
• • Часовая квота: сбрасывается на границе UTC-часа.
• • Автопауза: после 5 нарушений лимита за час (любого уровня — min-interval, burst или часовая квота) endpoint автоматически выключается (is_active=false). Владельцу уведомление в Telegram-бот. Включается обратно вручную через UI после устранения причины — авто-восстановления нет, чтобы цикл «пауза→повторный абьюз→пауза» не повторялся.

Лимит постов (как у обычных целей): каждая успешная публикация webhook-поста = 1 пост в месячной квоте тарифа. Не путайте с rate limit (защита от абьюза) и квотой постов (биллинг).

Дополнительные защиты webhook IN

Помимо HTTPS + Bearer-токена, в карточке endpoint'а доступны опциональные защиты для повышенной безопасности.

• HMAC-подпись от отправителя. Defense-in-depth: отправитель подписывает body своим секретом, мы проверяем. Даже если Bearer-токен утечёт — без секрета подделать запрос не получится. Включается toggle в карточке endpoint'а. Проверка идентична нашему OUT-варианту (см. ниже про Webhook OUT) — алгоритм один, клиенту достаточно одной функции для приёма и отправки. Примеры кода — ниже.
• Replay protection через timestamp. При require_timestamp=on требуем заголовок X-Crosslybot-Timestamp (Unix seconds) в окне ±5 мин. Защита от replay-атак если body+token утекли в логи или были перехвачены: запрос валиден только в 5-минутном окне, потом — 401.
• IP allowlist (CIDR). Список IP/CIDR из которых принимаем запросы. Запросы с других адресов получают идентичный 401 (timing-safe, не раскрываем что allowlist настроен). Имеет смысл если у отправителя статичный IP — для облачных SaaS (n8n cloud, Zapier, Make, AWS Lambda) IP-пулы плавающие, тогда лучше не использовать.
• Ротация публичного URL. Если адрес webhook'а попал в открытые источники — нажмите «Rotate URL» в карточке. Сгенерируется новый /v1/webhooks/<new-slug>, старый мгновенно перестаёт работать. Cooldown 24 ч от случайных кликов. Endpoint, токен и все привязки в проектах при ротации сохраняются — после ротации просто обновите URL у всех отправителей.
• История запросов в UI. На странице endpoint'а — последние 100 запросов с фильтрами по статусу. Виден IP, decision, причина, latency, размер payload. Удобно для отладки интеграции и расследования инцидентов.

Подпись запроса от отправителя (если включён require_signature)

Алгоритм: HMAC-SHA256(secret, raw_body) → hex → заголовок X-Crosslybot-Client-Signature: sha256=<hex>. Принимается также формат без префикса sha256= и регистр hex (UPPERCASE/lowercase). Подпись валидируется до основной обработки запроса; при несовпадении — идентичный 401 (как для невалидного токена, timing-safe).

SECRET="ваш-сгенерированный-secret"
BODY='{"text":"привет"}'
SIG=$(printf "%s" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $NF}')

curl -X POST https://wh.crosslybot.ru/v1/webhooks/<slug> \
  -H "Authorization: Bearer crossly_live_..." \
  -H "Content-Type: application/json" \
  -H "X-Crosslybot-Client-Signature: sha256=$SIG" \
  --data-binary "$BODY"

import hmac, hashlib, json, requests

SECRET = "ваш-secret"
body_bytes = json.dumps({"text": "привет"}).encode("utf-8")
signature = hmac.new(SECRET.encode(), body_bytes, hashlib.sha256).hexdigest()

resp = requests.post(
    "https://wh.crosslybot.ru/v1/webhooks/<slug>",
    headers={
        "Authorization": "Bearer crossly_live_...",
        "Content-Type": "application/json",
        "X-Crosslybot-Client-Signature": f"sha256={signature}",
    },
    data=body_bytes,  # ВАЖНО: data=, не json= — нужны точные байты
)

import { createHmac } from "crypto";

const SECRET = "ваш-secret";
const body = JSON.stringify({ text: "привет" });
const signature = createHmac("sha256", SECRET).update(body).digest("hex");

await fetch("https://wh.crosslybot.ru/v1/webhooks/<slug>", {
  method: "POST",
  headers: {
    "Authorization": "Bearer crossly_live_...",
    "Content-Type": "application/json",
    "X-Crosslybot-Client-Signature": `sha256=${signature}`,
  },
  body, // ВАЖНО: точные байты, не пересериализовывать
});

import (
    "bytes"
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "net/http"
)

secret := []byte("ваш-secret")
body := []byte(`{"text":"привет"}`)

mac := hmac.New(sha256.New, secret)
mac.Write(body)
sig := hex.EncodeToString(mac.Sum(nil))

req, _ := http.NewRequest("POST", "https://wh.crosslybot.ru/v1/webhooks/<slug>", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer crossly_live_...")
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-Crosslybot-Client-Signature", "sha256="+sig)
http.DefaultClient.Do(req)

⚠ Подпись считается от точных байтов body. Если ваша HTTP-библиотека пересериализует JSON между подписью и отправкой — подпись не сойдётся, получите 401. Используйте data=bytes / --data-binary / эквиваленты.

Webhook OUT: проверка HMAC-подписи

Когда Crosslybot отправляет пост на ваш URL (исходящий webhook), мы подписываем тело запроса HMAC-SHA256 и кладём подпись в заголовок X-Crosslybot-Signature. Это позволяет приёмнику убедиться что запрос действительно от Crosslybot.

X-Crosslybot-Signature: sha256=<hex>
X-Crosslybot-Delivery-Id: <uuid>
X-Crosslybot-Timestamp: <unix-seconds>
X-Crosslybot-Event: post.published
Idempotency-Key: <uuid>
Content-Type: application/json

import hmac, hashlib

def verify(secret: str, raw_body: bytes, header_signature: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode("utf-8"), raw_body, hashlib.sha256
    ).hexdigest()
    # constant-time сравнение чтобы избежать timing-атак
    return hmac.compare_digest(expected, header_signature)

# Пример (Flask):
# raw = request.get_data()
# sig = request.headers["X-Crosslybot-Signature"]
# if not verify(SECRET, raw, sig): abort(401)

Управление токенами

• • Plaintext показывается ОДИН раз — при создании или rotate. Сохраните сразу в свой secret-менеджер
• • Префиксы: crossly_live_ для прода, crossly_test_ для тестирования (легко искать в логах)
• • Rotate: мгновенная замена. Старый токен немедленно перестаёт работать
• • Revoke: в UI можно отозвать токен или временно деактивировать endpoint
• • Несколько токенов: в MVP — один активный токен на endpoint. Если нужно дать токен второй интеграции — создайте отдельный webhook