Webhooks

{
  "requestId": "1710432000_abc123def",
  "phase": "primary",
  "visitorId": "X7fh2Hg9LkMn3pQr",
  "linkedId": "user_12345",
  "tag": "login",
  "timestamp": "2024-03-12T16:00:00Z",
  "url": "https://your-app.com/login",
  "ip": "94.142.239.124",
  "userAgent": "Mozilla/5.0 …",
  "browser": { "name": "Chrome", "version": "120.0" },
  "os": { "name": "macOS", "version": "14.3" },
  "device": "desktop",
  "geo": {
    "country": "CZ",
    "city": "Prague",
    "lat": 50.05,
    "lon": 14.4,
    "timezone": "Europe/Prague",
    "isp": "Example ISP"
  },
  "network": {
    "vpn": false,
    "proxy": false,
    "tor": false,
    "datacenter": false,
    "connectionType": "residential"
  },
  "bot": {
    "result": "human",
    "type": "",
    "score": 0.02
  },
  "identification": {
    "confidence": 0.95,
    "incognito": false,
    "visitType": "returning"
  },
  "decision": {
    "action": "allow",
    "riskScore": 4,
    "suspectScore": 0.08
  }
}

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 we can verify the signature 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 {
  // Parse "t=...,v1=..."
  const parts = Object.fromEntries(header.split(",").map((kv) => kv.split("=") as [string, string]))
  const t = parts["t"]
  const v1 = parts["v1"]
  if (!t || !v1) return false

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

  const a = Buffer.from(v1, "hex")
  const b = Buffer.from(expected, "hex")
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

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")
})

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

{
  "ok": true,
  "data": {
    "id": "wh_abc123",
    "workspaceEnvironmentId": "b201f2ba-…",
    "url": "https://your-server.com/webhook/tracio",
    "events": [],
    "signingSecret": "f3a9…<hex>",
    "status": "active",
    "successRate": 100,
    "createdAt": "2024-03-12T16:00:00Z"
  }
}

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")
})

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