Перейти к содержимому
Доставка данных

Ваши данные там, где вы принимаете решение

Каждая идентификация может дойти до ваших систем двумя путями: прилететь на ваш сервер в момент события или быть запрошенной вами ровно в ту секунду, когда вы решаете. Оба канала несут одни и те же числа — это закреплено тестом, а не обещанием.

Начать бесплатноЗаказать демо
Два канала

Push или pull

Вебхуки шлют вам события по мере их появления. Data API позволяет спросить в тот момент, когда вам нужен ответ. Большинство команд держат оба: вебхуки — чтобы фиксировать и реагировать, Data API — чтобы проверять на лету.

Вебхуки — push, в реальном времени

Мы шлём POST с подписанным JSON-событием на ваш эндпоинт в момент, когда что-то происходит: посетитель идентифицирован, отмечен захват аккаунта, началась атака ботов. Ничего не надо опрашивать и ничего не надо расписывать по расписанию.

Лучше всего для: фиксации каждого визита, реакции на атаки, наполнения хранилища или SIEM.

Задержка доставки p50 — 44–140 мс от события до вашего эндпоинта.

Data API — pull, по требованию

Приватный API server-to-server. Ваш бэкенд аутентифицируется секретным ключом и читает ровно то, что мы знаем о посетителе, в ту секунду, когда он решает, — обычно внутри обработчика входа или оформления заказа.

Лучше всего для: проверки на лету перед списанием с карты, одобрением регистрации или разблокировкой аккаунта.

Доступно с тарифа Pro.

Вебхуки

Четыре типа события, один конверт

Каждая доставка приходит в одном и том же конверте, тип события — и в теле, и в заголовке X-Tracio-Event-Type, так что один обработчик может разводить все четыре.

Посетитель идентифицирован

Основное событие: визит оценён. Несёт ID посетителя, браузер и ОС, гео и сеть, вердикт по ботам и решение по риску. Доставляется фазами — основное событие при загрузке страницы, затем поздняя или корректирующая фаза, когда медленные улики меняют вердикт. Фазы связываются по requestId.

identification

Захват аккаунта

На визите сработал детектор захвата аккаунта: устройство за известным аккаунтом больше не похоже на устройство его владельца. Приходит отдельным событием, с приложенным контекстом аккаунта, а не прячется внутри тела идентификации.

account_takeover

Атака ботов

Всплеск автоматизированного трафика в вашем воркспейсе. За этим событием визита нет — это оповещение уровня воркспейса, поэтому блоки визита в теле просто отсутствуют, а не приезжают пустыми оболочками с обнулёнными оценками.

attack_detected

Изменение репутации

Профиль перешёл между репутационными полосами. Тот же конверт, что и у оповещения об атаке: событие уровня профиля без привязанного визита, несущее новую полосу и предыдущую.

reputation_changed

Доставка, в сокращении

Это базовое тело. Pro добавляет скорость визитов; Business добавляет коды причин вердикта, поведенческие сигналы, guidance и кросс-браузерные данные устройства — в ровно ту же форму: новые блоки появляются, существующие пути никогда не сдвигаются.

JSON
{
  "version": 2,
  "event": "identification",
  "eventId": "req_8f21c4:primary",
  "requestId": "req_8f21c4",
  "phase": "primary",
  "visitorId": "3f9a1b2c4d5e6f70",
  "timestamp": "2026-07-30T12:00:00Z",
  "geo": { "country": "DE", "city": "Berlin", "timezone": "Europe/Berlin" },
  "network": { "vpn": true, "proxy": false, "tor": false, "datacenter": false },
  "bot": { "result": "human", "score": 12 },
  "identification": { "confidence": 0.97, "incognito": false },
  "decision": { "action": "suspicious", "riskScore": 65.9 }
}

Каждый запрос несёт две подписи

X-Tracio-Signature — это HMAC-SHA256 по временной метке подписи, склеенной с сырым телом запроса, на ключе вашего секрета вебхука: она доказывает, что отправитель знает секрет, который есть у вас обоих. X-Tracio-Signature-Ed25519 — подпись платформы: вы проверяете её открытым ключом, который забираете с well-known-эндпоинта, поэтому хранить у себя нечего. Временная метка входит в подписанное содержимое — именно это делает старый перехват бесполезным для повторной отправки.

Проверяйте по сырым байтам запроса — пересериализованный JSON меняет байты, и подпись не сойдётся. Повторы несут тот же X-Tracio-Event-Id, поэтому дедуплицируйте по нему.

Заголовки в каждой доставке

Text
X-Tracio-Signature:         t=1753444800,v1=5257a869e7ecebed...
X-Tracio-Signature-Ed25519: t=1753444800,kid=k1,v1=0Zx0M0n8...
X-Tracio-Event-Type:        identification
X-Tracio-Event-Id:          req_8f21c4:primary
X-Tracio-Delivery-Attempt:  1
X-Tracio-Payload-Version:   2
Надёжность

Построено так, чтобы не терять события

Доставка работает на выделенном парке узлов, и источник истины — очередь, а не память процесса. Именно это делает at-least-once настоящим: если узел доставки умирает на полпути, событие всё ещё в очереди, и его забирает другой узел.

событий в секунду через один вебхук — против примерно 50 до июльской перестройки
44–140 msзадержка доставки p50 от события до вашего эндпоинта
попыток доставки по расширяющейся лестнице, растянутых максимум на 8,7 часа
из 90 000 событий доставлено на учениях, где узел доставки убивали под нагрузкой

Повторы под настоящие сбои

5 с, 30 с, 2 мин, 10 мин, 30 мин, 2 ч, 6 ч. Первые повторы укладываются в минуту, так что короткий перезапуск вашего сервиса вам ничего не стоит. Каждая пауза берётся случайно между половиной указанного значения и полным — чтобы повторы не вернулись одним залпом после сбоя.

Автоотключение, которое не срабатывает зря

Вебхук выключается только тогда, когда сбои и достигли порога, и держатся не меньше 15 минут подряд, — всплеск накопившихся доставок во время перезапуска интеграцию не убьёт. 410 Gone отключает сразу. В дашборде видны причина, код ответа и кнопка включения обратно.

Ротация секрета без разрыва

После ротации оба секрета остаются действительными 24 часа, и заголовок несёт обе подписи — совпадения любой из них достаточно. Вы обновляете конфигурацию внутри окна, а не гоняетесь за моментом переключения; «Отозвать сейчас» обрывает окно, когда нужно закрыть его немедленно.

Журнал доставок, который можно читать

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

Data API

Спрашивайте в момент решения

Приватный API server-to-server на api.tracio.ai. Ваш бэкенд аутентифицируется секретным ключом и читает собственные данные. Он намеренно не отдаёт CORS-заголовков: секретный ключ открывает доступ ко всему в вашем воркспейсе и не должен попадать в браузер никогда. Доступно с тарифа Pro.

МетодПутьВозвращает
GET/v1/visitors/{visitorId}Сводка по посетителю: первый и последний визит, число визитов, уникальные IP и страны, браузеры и устройства, история риска — плюс его последняя сессия.
GET/v1/visitors/{visitorId}/sessionsСписок сессий с курсорной пагинацией и фильтрами по диапазону дат, результату по ботам и минимальной оценке риска.
GET/v1/visitors/{visitorId}/sessions/latestПоследняя сессия одним объектом, без обёртки списка.
GET/v1/sessions/{requestId}Одна конкретная сессия. Передайте рядом visitorId — и поиск пойдёт через индекс посетителя, а не по всей вашей истории.
GET/v1/visitors/{visitorId}/velocityАктивность за окно — 1h, 24h или 7d: сколько визитов, с скольких IP, из скольких стран, под сколькими аккаунтами.

Проверка посетителя на оформлении заказа

Типичный вызов: внутри вашего платёжного обработчика, до авторизации карты. Один запрос, один ответ — и блок meta сообщает, какое окно вы на самом деле получили: если вы просите полгода, а ваш тариф хранит 30 дней, вернутся 30 дней, и об этом будет сказано.

Запрос

bash
# Inside your checkout handler, before you authorize the card
curl -s -H "Authorization: Bearer $TRACIO_SECRET_KEY" \
  "https://api.tracio.ai/v1/visitors/3f9a1b2c/velocity?window=24h"

Ответ

JSON
{
  "window": "24h",
  "events": 128,
  "uniqueIps": 4,
  "uniqueCountries": 2,
  "uniqueAccounts": 1,
  "meta": { "plan": "business", "retentionDays": 30 }
}

Одни и те же числа везде

Визит, который набирает 65,9 в вашем дашборде, набирает 65,9 в Data API и 65,9 в теле вебхука. Два независимых рендера могли бы разойтись — классический способ это шкалы, когда один канал отдаёт вам 0,93 там, где другой говорит 93, — поэтому тест паритета строит один визит, прогоняет его через оба канала и сравнивает публичные поля на сыром JSON. Совпадение обеспечено, а не заявлено.

Guidance — с тарифа Business

Совет, а не только числа

Оценки говорят, что мы увидели. Guidance говорит, что с этим делать, — для четырёх решений, которые реально стоят денег. Считается версионированными правилами, с приложенным обоснованием.

Принимать платёж?

Взвешивает риск, фрод-репутацию и вердикт по ботам до того, как вы авторизуете карту.

Принимать регистрацию?

Ловит одноразовый аккаунт до того, как он появится: мультиаккаунтинг и репутация весят здесь больше всего.

Пускать внутрь?

Автоматически ужесточается, когда на визите сработал детектор захвата аккаунта.

Засчитывать конверсию?

Отделяет настоящий реферал от самореферала или бота, которому заплатили.

Словарь из четырёх слов

allowНичего, на что стоит реагировать.
challengeЗапросить второй фактор.
reviewПридержать для человека.
denyОтказать прямо.

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

Один расчёт, три канала

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

JSON
"guidance": {
  "version": 1,
  "overall": "review",
  "payment": "review",
  "registration": "challenge",
  "login": "allow",
  "affiliate": "allow",
  "basis": ["risk", "fraud_reputation"]
}
Интеграция

Пять SDK на фронте, два канала на бэке

Браузерная сторона выпускается как пять SDK — vanilla JavaScript, React, Vue 3, Angular и Svelte 5. Серверных SDK нет, и это сделано намеренно: ваш бэкенд интегрируется по обычному HTTP через подписанные вебхуки и Data API. Проверка подписи — это десяток строк против опорного вектора, который мы публикуем, и в дереве серверных зависимостей нет ничего лишнего, что пришлось бы постоянно обновлять.

Браузерные SDK
JavaScriptReactVue 3AngularSvelte 5
Посмотреть SDKСправочник APIДокументация по вебхукам
FAQ

Частые вопросы

Соберите всё за один вечер

Создайте вебхук в дашборде, направьте его на свой эндпоинт и нажмите «Тест». Проверьте подпись по нашему опорному вектору — и самое сложное позади.

Начать бесплатноЗаказать демо