Webhooks

{
  "version": 2,
  "event": "identification",
  "eventId": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31:primary", // "<requestId>:<phase>" — the idempotency key
  "requestId": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31", // visit identifier, shared by all phases
  "phase": "primary",
  "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "linkedId": "user-42", // your ?lid=, if you passed one
  "tag": "checkout",
  "timestamp": "2026-07-30T12:00:00Z",
  "url": "https://shop.example.com/checkout",
  "ip": "203.0.113.44",
  "userAgent": "Mozilla/5.0 …",
  "browser": { "name": "Chrome", "version": "138" },
  "os": { "name": "macOS", "version": "15.5" },
  "device": "desktop",
  "gpu": "Intel Iris Plus Graphics 655", // 비디오 어댑터 모델, 정규화됨. 알 수 없으면 존재하지 않음
  "geo": {
    "country": "DE",
    "city": "Berlin",
    "lat": 52.52,
    "lon": 13.405,
    "timezone": "Europe/Berlin"
  },
  "network": {
    "vpn": false,
    "proxy": true,
    "tor": false,
    "datacenter": true,
    "connectionType": "DCH",
    "proxyDetected": true // HTTP 트래픽과 원시 네트워크 경로가 서로 다른 네트워크로 나감
  },
  "bot": { "result": "human", "score": 3.2 }, // human | bot | uncertain
  "identification": { "confidence": 0.97, "incognito": false },
  "decision": { "action": "real", "riskScore": 12.2 } // real | fake | suspicious
}

{
  "identification": {
    "matchType": "exact", // exact | fuzzy | new — how the visitor was recognized
    "matchConfidence": 0.93,
    "visits": 42,
    "incognitoVisits": 3
  },
  // Present when visitor counters are available at event time (usually primary).
  // A missing block means "no data", not "zeros".
  "velocity": { "events5m": 7, "uniqueIps": 2, "uniqueLocations": 1 },
  "bot": { "antidetectScore": 0 }, // antidetect indicators, 0..100
  "session": { "durationSeconds": 95 } // where the visit duration is already known
}

{
  "reasons": [                  // at most 8, sorted by importance
    { "code": "headless_browser", "severity": "high" },
    { "code": "privacy_hardening", "severity": "low" }
  ],
  // Behavioral biometrics — present only when behavioral scoring ran for the
  // visit. A missing block means "no data", never "nothing suspicious".
  "behavior": { "score": 87, "verdict": "human", "confidence": 0.92 },
  "identification": { "driftScore": 0.31 },  // divergence from the account profile
  "deviceInfo": {
    "deviceId": "…",            // the physical device across browsers on it
    "crossBrowser": true,
    "confidence": 0.88,
    "linkedBrowsers": 3
  },
  "network": {
    "isp": "Deutsche Telekom", "asn": 3320,
    // 원시 네트워크 경로에서 관측된 공인 주소, 즉 프록시나 VPN 뒤에 있는 주소.
    // 그런 주소가 관측되지 않으면 존재하지 않음
    "realIp": { "address": "203.0.113.7", "country": "NL", "isp": "KPN" }
  },
  // 리눅스 머신에서 실제로 측정된 데스크톱 환경("Mint 22+", "Ubuntu",
  // "GNOME", "KDE"). User-Agent는 배포판을 표현할 수 없음. 판별되지 않으면
  // 존재하지 않으며, 대부분의 리눅스 방문과 리눅스가 아닌 모든 방문이 여기에
  // 해당함.
  "osEnvironment": "Mint 22+",
  // 방문이 스스로 주장한 바와 독립적인 검사가 측정한 바의 대비. 위조가
  // 실제로 탐지되었을 때만 존재함. `real` 필드가 비어 있다는 것은 "검사가
  // 침묵했다"는 뜻이지 "확인됨"이 아님. `gpu` 축에서는 `claimed.gpu`가
  // 주장된 어댑터를 최상위 `gpu` 필드와 동일한 읽기 쉬운 모델 이름으로 담음.
  "spoofing": {
    "detected": true,
    "claimed": { "os": "Windows 10", "browser": "Chrome 139.0" },
    "real": { "os": "macOS" },
    "spoofedAxes": ["os", "screen"],          // os | gpu | screen | network | browser
    "anonymousBrowser": { "detected": true, "names": ["Linken Sphere"] }
  },
  // 기기 사실 — 방문자의 브라우저가 머신에 대해 보고하는 내용으로, 당사
  // 측에서 정제한 것. screen: 해상도, 색 심도, device pixel ratio. locale:
  // 브라우저 자체가 선호하는 언어와 시간대로, IP 주소에서 도출되는
  // geo.timezone과는 다르며, 둘 사이의 불일치는 위치 위조의 흔한 신호임.
  // clientHints: User-Agent Client Hints — CPU 아키텍처와 비트 수, 기기
  // 모델(Android에서는 `model`의 모델 코드, 예: "SM-A556B", 그리고 Google
  // Play 기기 목록에 실린 마케팅 이름이 `deviceName`에, 예:
  // "Samsung Galaxy A55 5G"), 정확한 플랫폼 버전. Chromium 기반 브라우저만
  // 보고함.
  // 방문이 그런 데이터를 담지 않았다면 각 블록은 존재하지 않으므로 모두
  // 선택적인 것으로 다룰 것.
  "screen": { "width": 2560, "height": 1600, "colorDepth": 30, "pixelRatio": 2 },
  "locale": { "languages": ["en-US", "de"], "timezone": "Europe/Berlin" },
  "clientHints": { "architecture": "arm", "bitness": "64", "platformVersion": "15.5.0" },
  // 비디오 어댑터가 스스로를 가상이라고 밝힌 경우에만 존재함. hypervisor는
  // 닫힌 사전임(vmware, virtualbox, parallels, qemu, hyperv, bochs,
  // intel-gvt, vgpu). 블록이 없다는 것은 그런 증거가 없다는 뜻임.
  "environment": { "virtualMachine": true, "hypervisor": "vmware" },
  "decision": { "suspectScore": 55 },
  "guidance": { "version": 1, "overall": "review" }             // see below
}

{
  "guidance": {
    "version": 1,
    "overall": "review", // the strictest advice across the scenarios
    "payment": "review", // whether to accept the payment
    "registration": "challenge", // whether to create the account
    "login": "challenge", // whether to let them into the account
    "affiliate": "review", // whether to credit the conversion to the partner
    "basis": ["risk", "network"] // the axes that determined the advice
  }
}

{
  "version": 2,
  "event": "account_takeover",
  "eventId": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31:ato",
  "requestId": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31",
  "phase": "beacon", // 경보는 비컨에서 올라온다. "ato"라고 말하는 것은 eventId뿐
  "accountAlert": {
    "type": "behavior-drift",
    "accountId": "user-42", // your linkedId for the account
    "driftScore": 0.83
  }
  // …the remaining identification fields
}

{
  "version": 2,
  "event": "attack_detected",
  "eventId": "c0a8e1f2-…",
  "timestamp": "2026-07-30T12:00:00Z",
  "attack": {
    "kind": "bot_spike",
    "severity": "critical", // info | warning | critical
    "windowMinutes": 15,
    "recentBots": 4210,
    "recentTotal": 5100,
    "expected": 180.5 // the baseline expected over a window this size
  }
}

X-Tracio-Signature: t=1710432000,v1=5257a869e7ecebed…

// Express.js example
import express from "express"
import crypto from "crypto"

const app = express()

// Capture the raw body so the signature can be verified byte-for-byte.
app.use(
  express.json({
    verify: (req, _res, buf) => {
      ;(req as any).rawBody = buf
    },
  }),
)

function verifySignature(rawBody: Buffer, header: string, secret: string): boolean {
  if (!header) return false

  const parts = header.split(",").map((p) => p.trim())
  const ts = parts.find((p) => p.startsWith("t="))?.slice(2)
  if (!ts) return false

  // Replay protection: reject timestamps more than five minutes old.
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false

  // Sign the raw bytes: the "<t>." prefix plus the raw request body.
  const signed = Buffer.concat([Buffer.from(`${ts}.`, "utf8"), rawBody])
  const expected = crypto.createHmac("sha256", secret).update(signed).digest("hex")
  const exp = Buffer.from(expected, "hex")

  // During a rotation window the header carries several v1= — any may match.
  return parts.some((p) => {
    if (!p.startsWith("v1=")) return false
    const got = Buffer.from(p.slice(3), "hex")
    // Compare lengths BEFORE timingSafeEqual: it throws on differing lengths,
    // and one junk header would turn the handler into a 500.
    return got.length === exp.length && crypto.timingSafeEqual(got, exp)
  })
}

app.post("/webhook/tracio", (req, res) => {
  const header = req.headers["x-tracio-signature"] as string
  if (!verifySignature((req as any).rawBody, header, WEBHOOK_SECRET)) {
    return res.status(401).json({ error: "Invalid signature" })
  }

  const event = req.body
  console.log(`Visitor: ${event.visitorId}`)
  console.log(`Bot: ${event.bot?.result}`) // "human" | "bot" | "uncertain"

  res.status(200).send("OK")
})

app.post("/webhook/tracio", async (req, res) => {
  const eventId = req.headers["x-tracio-event-id"] as string

  const existing = await db.webhooks.findOne({ eventId })
  if (existing) return res.status(200).send("Already processed")

  await db.webhooks.insert({ eventId, processedAt: new Date() })
  await processWebhookEvent(req.body)

  res.status(200).send("OK")
})

curl -X POST https://app.tracio.ai/api/v1/workspaces/{wsId}/webhooks \
  -H "Authorization: Bearer <session-jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-server.com/webhook/tracio", "events": [] }'

{
  "ok": true,
  "data": {
    "id": "b3d4f8a1-2c67-4e9b-8f05-7a1d3c9e2b48",
    "workspaceEnvironmentId": "b201f2ba-…",
    "url": "https://your-server.com/webhook/tracio",
    "events": [],
    "signingSecret": "f3a9…<hex>",
    "status": "active",
    "successRate": 100,
    "createdAt": "2026-07-30T12:00:00Z"
  }
}

app.post("/webhook/tracio", async (req, res) => {
  res.status(200).send("OK")
  processWebhookEvent(req.body).catch(console.error)
})

async function processWebhookEvent(event: WebhookPayload) {
  await db.events.insert(event)

  if (event.decision?.riskScore > 50) {
    await alertFraudTeam(event)
  }

  if (event.bot?.result === "bot") {
    await blockVisitor(event.visitorId)
  }
}

ngrok http 3000
# Use the generated URL as your webhook endpoint