推送，还是拉取
Webhook 在事件发生时把它们推给您。Data API 让您在需要答案的那一刻发问。多数团队两者并用：用 Webhook 记录和响应，用 Data API 在流程中做内联检查。
Webhook — 实时推送
一有情况发生，我们就把一个签名的 JSON 事件 POST 到您的端点：某个访问者被识别、某次账户接管被标记、某轮机器人攻击开始。无需轮询，也无需安排定时任务。
适合：记录每一次访问、响应攻击、向数据仓库或 SIEM 灌数。
从事件到您的端点，p50 投递延迟 44–140ms。
Data API — 按需拉取
一个服务器到服务器的私有 API。您的后端用密钥认证，在它做决定的那一秒读取我们对某位访问者的全部已知信息——通常是在登录或结算处理逻辑内部。
适合：在扣款、通过注册或解锁账户之前做一次内联检查。
Pro 方案起可用。
四种事件类型，一个信封
每一次投递都装在同一个信封里，事件类型同时出现在正文和 X-Tracio-Event-Type 请求头中——因此一个处理函数就能路由全部四种。
访问者已识别
核心事件：一次访问完成了打分。它携带访问者 ID、浏览器与操作系统、地理与网络、机器人判定和风险决策。投递分阶段进行——页面加载时先有一个主事件，之后当较慢到达的证据改变了判定时，再有一个 late 阶段或修正阶段。各阶段之间用 requestId 关联。
identification账户接管
某次访问触发了账户接管检测器：某个已知账户背后的设备，看起来已不再是拥有该账户的那台设备。它作为独立事件到达并附带账户上下文，而不是藏在识别事件的正文里。
account_takeover机器人攻击
您的工作区出现了自动化流量的激增。只有这一种事件背后没有具体访问——它是工作区级别的告警，因此与访问相关的区块会直接从正文中缺席，而不是以评分归零的空壳形式送达。
attack_detected信誉变化
某个画像在信誉档位之间发生了移动。信封与攻击告警相同——一个不附带访问的画像级事件，携带新的档位和此前的档位。
reputation_changed一次投递（节选）
这是基础正文。Pro 会加上访问速度指标；Business 会在完全相同的结构上加上判定原因码、行为信号、指导建议和跨浏览器设备数据——新的区块会出现，已有的路径永远不会挪动。
{ "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 是以您的 Webhook 密钥为密钥、对签名时间戳与原始请求正文拼接后计算的 HMAC-SHA256，它证明发送方知道双方共同持有的那个密钥。X-Tracio-Signature-Ed25519 是平台签名：您用从 well-known 端点获取的公钥来验证，因此您这一侧无需保管任何机密。时间戳是被签名内容的一部分，这正是旧的抓包重放毫无用处的原因。
请针对原始请求字节进行验证——重新序列化 JSON 会改变字节，签名就对不上了。重试会携带相同的 X-Tracio-Event-Id，请据此去重。
每次投递都会带上的请求头
X-Tracio-Signature: t=1753444800,v1=5257a869e7ecebed...X-Tracio-Signature-Ed25519: t=1753444800,kid=k1,v1=0Zx0M0n8...X-Tracio-Event-Type: identificationX-Tracio-Event-Id: req_8f21c4:primaryX-Tracio-Delivery-Attempt: 1X-Tracio-Payload-Version: 2为“不丢事件”而建
投递跑在一组专用节点上，而真相来源是队列，不是某个进程的内存。这正是 at-least-once 得以成立的原因：如果一个投递节点在处理途中宕机，事件仍在队列里，另一个节点会接手。
贴合真实故障的重试
5 秒、30 秒、2 分钟、10 分钟、30 分钟、2 小时、6 小时。最初几次重试在一分钟内就会到达，因此服务短暂重启不会让您有任何损失。每次等待时长都在标称值的一半到标称值之间随机选取，所以故障结束后重试不会作为一波齐射同时返回。
不会误触发的自动停用
只有当失败既达到阈值、又已持续至少 15 分钟时，Webhook 才会被关闭——重启期间积压投递造成的一阵失败不会掐断集成。收到 410 Gone 则立即停用。仪表盘会显示原因、响应码和一个重新启用按钮。
没有空档的密钥轮换
轮换之后两个密钥会同时有效 24 小时，请求头也会同时携带两个签名，任意一个匹配即可。您可以在这个窗口内从容更新配置，而不必和切换时刻赛跑；需要立刻作废时，用“立即吊销”把窗口提前截断。
看得懂的投递日志
每一次尝试——响应码、耗时、错误文本——都能在仪表盘中按 Webhook 查看，旁边还有一个测试操作，可以向您的端点发送一份签名的示例载荷，让您在正式上线前确认自己的验签逻辑。
在您做决定的那一刻发问
一个位于 api.tracio.ai 的服务器到服务器私有 API。您的后端用密钥认证并读取自己的数据。它刻意不返回任何 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 天并明确说明。
请求
# Inside your checkout handler, before you authorize the cardcurl -s -H "Authorization: Bearer $TRACIO_SECRET_KEY" \ "https://api.tracio.ai/v1/visitors/3f9a1b2c/velocity?window=24h"响应
{ "window": "24h", "events": 128, "uniqueIps": 4, "uniqueCountries": 2, "uniqueAccounts": 1, "meta": { "plan": "business", "retentionDays": 30 }}各处数字一致
在仪表盘中打出 65.9 的一次访问，在 Data API 中是 65.9，在 Webhook 正文中同样是 65.9。两套独立的渲染是可能漂移的——量纲差异是最经典的一种，一边给您 0.93，另一边说 93——所以一项一致性测试会构造出同一次访问，让它经由两条通路渲染，并在原始 JSON 上比对公开字段。这种一致是被强制执行的，不是被声称的。
不只是数字，还有建议
评分告诉您我们看到了什么，指导建议告诉您该拿它怎么办——覆盖真正会造成金钱损失的四种决策，由带版本的规则计算得出，并附上判断依据。
这笔付款收不收？
在您授权扣款之前，权衡风险、欺诈信誉和机器人判定。
这个注册接不接？
在一次性账户诞生之前把它拦住——这里多账户滥用和信誉的分量最重。
放不放他进来？
当该次访问触发了账户接管检测器时，自动收紧。
这笔转化算不算？
把真实推荐与自我推荐或激励驱动的机器人区分开来。
四个词的词汇表
每个场景会得到四种答案之一，同时给出这个答案的依据——来自固定词汇表的决定性维度：机器人、风险、欺诈信誉、行为、多账户滥用、账户接管、网络、联盟模式。您始终知道是哪个维度让建议发生了变化，而无需看到任何信号名称、权重或阈值。
一次计算，三条通路
同一个指导建议区块随 Webhook 发出、在 Data API 中作答，并渲染在仪表盘的访问者卡片上——一套规则、一个结果，您这边无需做任何对账。请读取与您场景对应的那条建议，而不是总体值：总体值只是四者中最严格的那一个，是给仪表盘看的汇总，而不是支付决策依据。规则版本随载荷一同下发，因此规则变更是您能立刻察觉的事，而不是从建议的偏移中推断出来的事。
"guidance": { "version": 1, "overall": "review", "payment": "review", "registration": "challenge", "login": "allow", "affiliate": "allow", "basis": ["risk", "fraud_reputation"]}前端五个 SDK，后端两条通路
浏览器侧以五个 SDK 形式提供：原生 JavaScript、React、Vue 3、Angular 和 Svelte 5。我们没有服务端 SDK，这是刻意为之：您的后端通过签名 Webhook 和 Data API，以纯 HTTP 方式集成。对照我们公开的参考向量，验签只需十来行代码，您的服务端依赖树里也不会多出一个需要持续升级的东西。