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

Ваші дані там, де ви ухвалюєте рішення

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

Почати безкоштовноЗамовити демо
Два канали

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

Поширені запитання

Зберіть усе за один вечір

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

Почати безкоштовноЗамовити демо