Los webhooks entregan los eventos de identificación a su servidor en tiempo real.
Cada vez que se identifica a un visitante, TRACIO envía una petición HTTP POST a la
URL de webhook que haya configurado. El cuerpo de la petición es el payload del
evento.
Son además el único canal que entrega los veredictos tardíos: aquellos en los que el comportamiento de un visitante demostró que estaba automatizado después de que la página ya se hubiera cargado.
Se configuran en el panel, en Settings → Webhooks. Los webhooks requieren el plan Pro o superior.
| Evento | Cuándo | Plan |
|---|---|---|
identification | En cada visita — las fases primary, late y correction | Todos |
account_takeover | El comportamiento bajo una cuenta ya no coincide con el perfil de su titular | Business+ |
account_assessment | El estado de evaluación de secuestro de una cuenta: evaluada y sin divergencia, evaluada y divergente, o no evaluada | Business+ |
attack_detected | Un pico de bots en su sitio | Business+ |
reputation_changed | La reputación de una persona vinculada ha pasado a otra banda | Business+ |
transaction_state_changed | Ha cambiado el resultado de una transacción que envió a POST /v2/transactions | Business+ |
login_risk | Una evaluación de login de POST /v2/logins/assess terminó con challenge o review | Todos |
trusted_device_enrolled | Un dispositivo pasó a ser de confianza para una cuenta, o se renovó su confianza | Todos |
trusted_device_revoked | Se revocó la confianza de un dispositivo — a través de la API o desde el panel | Todos |
affiliate_threshold_crossed | La recomendación para un afiliado empeoró (none → review, none → hold, review → hold) | Todos |
Los nombres de evento usan guiones bajos, nunca puntos: no existe visitor.created ni
session.created.
Un webhook se suscribe a tipos concretos; el valor aparte * significa «todos los
tipos, incluidos los que se añadan más adelante». Cinco tipos son la excepción: *
no incluye account_assessment, login_risk, trusted_device_enrolled,
trusted_device_revoked ni affiliate_threshold_crossed; nombre cada uno de ellos
explícitamente. account_assessment informa de la cobertura y no de un hallazgo,
así que llega aproximadamente una vez por visita que lleve un linked_id: un orden de
volumen distinto del de los demás eventos. Los tipos de riesgo de login y de afiliados
solo tienen sentido para una integración que llame a esas API. Un comodín configurado
antes de que existieran estos eventos no equivale a consentir recibirlos.
Un tipo desconocido se rechaza con 400 al crear o editar una suscripción, de modo
que una errata no puede dejarle un webhook que nunca se dispara en silencio.
identificationUna sola visita produce hasta tres entregas que comparten el mismo request_id:
primary — el veredicto inicial, en la carga de la página.late — enriquecimiento unos nueve segundos después, una vez han llegado las comprobaciones lentas.correction — una corrección basada en el comportamiento (puntero, teclado, desplazamiento).Correlaciónelas por request_id y distíngalas por phase. La fase posterior tiene
prioridad: si primary dijo human y correction dice bot, la respuesta correcta
es la segunda.
No se fíe del orden de llegada. Cada fase se entrega de forma independiente y con
su propio calendario de reintentos: si primary entró en reintento mientras late
tuvo éxito al primer intento, las recibirá en orden inverso. Determine la prioridad a
partir del campo phase, no de la hora de recepción.
Esas tres son las únicas fases de un evento identification. Un valor más le llega:
account_takeover y account_assessment llevan phase: "beacon", porque ambos se
generan desde el beacon de comportamiento de la sesión.
Fíjese en el desajuste que esto crea, porque afecta a la idempotencia. Una entrega
identification de producción tiene un event_id que es exactamente
<request_id>:<phase>, pero otras entregas rompen esa fórmula. Un account_takeover
es <request_id>:ato — el sufijo es el literal ato, no el valor del campo phase —
y un account_assessment es <request_id>:ato-state-<state>. Una entrega de prueba
enviada desde el panel es <request_id>:test, mientras que el phase de su cuerpo
sigue indicando primary; y un cuerpo de esquema 1 no tiene campo phase en
absoluto, así que el encabezado es el único sitio donde aparece ese sufijo. Use
event_id directamente como clave de idempotencia y nunca lo reconstruya a partir de
request_id y phase. Compare con los valores que trata y pase por alto cualquier
otro en lugar de rechazar la entrega.
Algunos eventos no tienen visita: attack_detected (nivel de workspace),
reputation_changed (nivel de persona), transaction_state_changed (nivel de
transacción), login_risk, trusted_device_enrolled y trusted_device_revoked
(nivel de cuenta) y affiliate_threshold_crossed (nivel de afiliado). No tienen
request_id, ni visitor_id, ni ninguno de los bloques browser, geo, bot o
decision — esas claves sencillamente no están, igual que el encabezado
X-Tracio-Request-Id. account_takeover y account_assessment, en cambio, los
produce una visita concreta y llevan el cuerpo de identificación completo
correspondiente a su plan. Si procesa todos los eventos en un mismo manejador,
compruebe event antes de tocar campos de visita.
Los webhooks nuevos usan la versión 3 del payload. Los webhooks existentes en la versión 1 o 2 conservan la versión que seleccionaron; ambos esquemas antiguos están congelados y se retirarán el 2027-04-12. Para migrar, seleccione la versión 3 en la tarjeta del webhook en el panel.
| Versión | Estado |
|---|---|
1 | Congelada; se retira el 2027-04-12 |
2 | Congelada; se retira el 2027-04-12 |
3 | El valor por defecto para webhooks nuevos; claves snake_case |
La versión 3 lleva los mismos campos y valores que la versión 2, con claves en
snake_case y un version: 3 de nivel superior. El algoritmo de firma y los
encabezados no cambian (X-Tracio-Payload-Version: 3). Las claves dentro de su propio
diccionario fields son datos suyos y no se renombran.
| v2 | v3 |
|---|---|
eventId | event_id |
requestId | request_id |
visitorId | visitor_id |
linkedId | linked_id |
userAgent | user_agent |
network.connectionType | network.connection_type |
network.proxyDetected | network.proxy_detected |
network.realIp | network.real_ip |
bot.antidetectScore | bot.antidetect_score |
identification.matchType | identification.match_type |
identification.matchConfidence | identification.match_confidence |
identification.incognitoVisits | identification.incognito_visits |
identification.driftScore | identification.drift_score |
decision.riskScore | decision.risk_score |
decision.suspectScore | decision.suspect_score |
deviceInfo | device_info |
deviceInfo.deviceId | device_info.device_id |
deviceInfo.crossBrowser | device_info.cross_browser |
deviceInfo.linkedBrowsers | device_info.linked_browsers |
screen.colorDepth | screen.color_depth |
screen.pixelRatio | screen.pixel_ratio |
clientHints | client_hints |
clientHints.platformVersion | client_hints.platform_version |
clientHints.deviceName | client_hints.device_name |
osEnvironment | os_environment |
environment.virtualMachine | environment.virtual_machine |
spoofing.spoofedAxes | spoofing.spoofed_axes |
spoofing.anonymousBrowser | spoofing.anonymous_browser |
session.durationSeconds | session.duration_seconds |
velocity.uniqueIps | velocity.unique_ips |
velocity.uniqueLocations | velocity.unique_locations |
accountAlert | account_alert |
accountAlert.accountId | account_alert.account_id |
accountAlert.driftScore | account_alert.drift_score |
accountAssessment | account_assessment |
accountAssessment.accountId | account_assessment.account_id |
accountAssessment.profile.windowsEffective | account_assessment.profile.windows_effective |
accountAssessment.profile.oldestWindowAgeSeconds | account_assessment.profile.oldest_window_age_seconds |
attack.windowMinutes | attack.window_minutes |
attack.recentBots | attack.recent_bots |
attack.recentTotal | attack.recent_total |
personId | person_id |
reputation.overallRisk | reputation.overall_risk |
linkedAccountsCount | linked_accounts_count |
linkedVisitorsCount | linked_visitors_count |
reputationChange | reputation_change |
reputationChange.personId | reputation_change.person_id |
reputationChange.previousBand | reputation_change.previous_band |
reputationChange.visitorIds | reputation_change.visitor_ids |
reputationChange.linkedAccountsCount | reputation_change.linked_accounts_count |
{ "version": 3, "event": "identification", "event_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31:primary", // "<request_id>:<phase>" — the idempotency key "request_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31", // visit identifier, shared by all phases "phase": "primary", "visitor_id": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y", "linked_id": "user-42", // your ?lid=, if you passed one "tag": "checkout", "fields": { "order_ref": "A-1029", "plan": "pro" }, // custom fields that arrived with the visit "timestamp": "2026-07-30T12:00:00Z", "url": "https://shop.example.com/checkout", "ip": "203.0.113.44", "user_agent": "Mozilla/5.0 …", "browser": { "name": "Chrome", "version": "138" }, "os": { "name": "macOS", "version": "15.5" }, "device": "desktop", "gpu": "Intel Iris Plus Graphics 655", // modelo del adaptador de vídeo, normalizado; ausente cuando se desconoce "geo": { "country": "DE", "city": "Berlin", "lat": 52.52, "lon": 13.405, "timezone": "Europe/Berlin" }, "network": { "vpn": false, "proxy": true, "tor": false, "datacenter": true, "connection_type": "DCH", "proxy_detected": true // el tráfico HTTP y la ruta de red en bruto salen por redes distintas }, "bot": { "result": "human", "score": 3.2 }, // human | bot | uncertain "identification": { "confidence": 0.97, "incognito": false }, "decision": { "action": "real", "risk_score": 12.2 }, // real | fake | suspicious "extensions": ["metamask", "privacy_badger"] // detected browser extensions; absent when none}Los valores cero y vacíos se omiten. Los campos de cadena y numéricos con valor
cero (bot.type para un humano, o bot.antidetect_score: 0, por ejemplo) no aparecen
en el JSON: no los haga obligatorios en sus esquemas y lea los bloques anidados de
forma defensiva.
bot.score y decision.risk_score son decimales en escala 0..100 con un dígito
tras la coma decimal, exactamente los números que el panel y la Data API informan para
esa misma visita. (En el esquema congelado v1 usan otras unidades: una fracción 0..1
y 0..255, respectivamente.)
bot.type es o el nombre de un bot reconocido, o un agente de IA verificado
(ai_agent:<vendor>), o una etiqueta de familia. Consulte
Tipos de bot para conocer el vocabulario: los nombres
internos de las comprobaciones no se exponen nunca, en ningún plan.
ai_agent:<vendor> significa que la petición demostró proceder de la infraestructura
de ese proveedor — una firma Web Bot Auth válida hecha con una clave que el proveedor
publica, o una dirección dentro de los rangos IP que el proveedor publica — y no que
simplemente lo afirme en el user agent. Una petición que dice ser un agente de IA y a
la que contradicen todas las pruebas que publica el proveedor se informa como
impersonation.
| Campo | Tipo | Descripción |
|---|---|---|
version | number | Versión del esquema del payload (3) |
event | string | Tipo de evento |
event_id | string | Identificador de la entrega — la clave de idempotencia; único por evento y compartido por todos sus webhooks que lo reciben, estable entre reintentos |
request_id | string | Identificador de la visita (UUID), compartido por todas sus fases |
phase | string | primary, late, correction; account_takeover y account_assessment llevan beacon |
visitor_id | string | Identificador de visitante estable |
linked_id | string | Identificador vinculado proporcionado por el cliente |
tag | string | Etiqueta personalizada proporcionada por el cliente |
fields | object | Campos personalizados adjuntos a la visita en el momento de la recogida. Solo lo que llegó con la visita: un campo adjuntado más tarde a través de la Data API no aparece nunca en un webhook, en ninguna fase ni reintento. Claves y valores son cadenas. Ausente cuando la visita no traía campos |
timestamp | string | Hora del evento (RFC 3339) |
url | string | URL de la página donde se capturó el evento |
ip | string | Dirección IP del cliente |
user_agent | string | Cadena de user-agent sin procesar del cliente |
browser.name / .version | string | Navegador detectado |
os.name / .version | string | Sistema operativo detectado |
device | string | Clase de dispositivo (p. ej. desktop, mobile) |
gpu | string | Modelo del adaptador de vídeo tal como lo informa el navegador (WebGL), normalizado a un nombre legible (Intel Iris Xe Graphics, Apple M1 Pro); Software renderer para rasterizadores por software; ausente cuando se desconoce |
geo | object | Geolocalización por IP: country, city, lat, lon, timezone |
network | object | vpn, proxy, tor, datacenter (booleanos) y connection_type |
network.proxy_detected | boolean | El tráfico HTTP de la visita y sus rutas de red en bruto salen por redes distintas — un proxy o una VPN delante del navegador. Dos direcciones del mismo proveedor (NAT del operador, una segunda salida de la misma VPN) no cuentan |
bot.result | string | human, bot o uncertain |
bot.type | string | Nombre del bot, agente de IA verificado o etiqueta de familia cuando se detecta un bot |
bot.score | number | Puntuación de bot (0–100) |
identification.confidence | number | Confianza de la identificación (0.0–1.0) |
identification.incognito | boolean | Contexto de navegación privada/incógnito |
decision.action | string | real, fake o suspicious |
decision.risk_score | number | Puntuación de riesgo agregada (0–100) |
extensions | array | Extensiones del navegador detectadas en esta visita, como slugs de máquina estables (los nombres, las categorías y los enlaces a la tienda están en el panel y en la Data API). Ausente cuando no se detectó nada |
Pro y superiores — cómo se comporta el visitante a lo largo del tiempo:
{ "identification": { "match_type": "exact", // exact | fuzzy | new — how the visitor was recognized "match_confidence": 0.93, "visits": 42, "incognito_visits": 3 }, // Present when visitor counters are available at event time (usually primary). // A missing block means "no data", not "zeros". "velocity": { "events5m": 7, "unique_ips": 2, "unique_locations": 1 }, "bot": { "antidetect_score": 0 }, // antidetect indicators, 0..100 "session": { "duration_seconds": 95 } // the correction phase and the account_takeover alert}Business y superiores — por qué el veredicto salió como salió:
{ "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 }, // The smoothed behavior score the account-takeover verdict was made on. It is // measured by beacons that arrive after the identification event, so it is // empty in identification deliveries — see the account_takeover event. "identification": { "drift_score": 0.41 }, "device_info": { "device_id": "…", // the physical device across browsers on it "cross_browser": true, "confidence": 0.88, "linked_browsers": 3 }, "network": { "isp": "Deutsche Telekom", "asn": 3320, // la dirección pública observada en la ruta de red en bruto, es decir, la // dirección detrás del proxy o de la VPN; ausente cuando no se observó // ninguna dirección así "real_ip": { "address": "203.0.113.7", "country": "NL", "isp": "KPN" } }, "geo": { "isp": "Deutsche Telekom" }, // El entorno de escritorio MEDIDO en una máquina Linux ("Mint 22+", // "Ubuntu", "GNOME", "KDE"); un User-Agent no puede expresar una // distribución. Ausente cuando no se determina — en la mayoría de las // visitas Linux y en todas las que no lo son. "os_environment": "Mint 22+", // Lo que la visita afirmó sobre sí misma frente a lo que midieron // comprobaciones independientes. Presente solo cuando realmente se detectó // una suplantación; un campo `real` vacío significa "la comprobación // guardó silencio", nunca "confirmado". Con el eje `gpu`, `claimed.gpu` // lleva el adaptador declarado con el mismo nombre de modelo legible que // el campo `gpu` de nivel superior. "spoofing": { "detected": true, "claimed": { "os": "Windows 10", "browser": "Chrome 139.0" }, "real": { "os": "macOS" }, "spoofed_axes": ["os", "screen"], // os | gpu | screen | network | browser "anonymous_browser": { "detected": true, "names": ["Linken Sphere"] } }, // Datos del dispositivo — lo que el navegador del visitante informa sobre // la máquina, saneado por nuestra parte. screen: resolución, profundidad // de color y device pixel ratio. locale: los idiomas preferidos y la zona // horaria del propio navegador — a diferencia de geo.timezone, que se // deriva de la dirección IP; una discrepancia entre ambos es una señal // habitual de una ubicación falseada. client_hints: User-Agent Client Hints // — arquitectura y bitness de la CPU, modelo del dispositivo (Android: el // código de modelo en `model`, p. ej. "SM-A556B", y su nombre comercial de // la lista de dispositivos de Google Play en `device_name`, p. ej. // "Samsung Galaxy A55 5G") y la versión exacta de la plataforma; solo los // navegadores basados en Chromium los informan. Cada bloque está ausente // cuando la visita no traía esos datos, así que trate cada uno como // opcional. "screen": { "width": 2560, "height": 1600, "color_depth": 30, "pixel_ratio": 2 }, "locale": { "languages": ["en-US", "de"], "timezone": "Europe/Berlin" }, "client_hints": { "architecture": "arm", "bitness": "64", "platform_version": "15.5.0" }, // Presente solo cuando el adaptador de vídeo se identificó a sí mismo como // virtual; hypervisor es un diccionario cerrado (vmware, virtualbox, // parallels, qemu, hyperv, bochs, intel-gvt, vgpu). Un bloque ausente // significa que no hay tal indicio. "environment": { "virtual_machine": true, "hypervisor": "vmware" }, "decision": { "suspect_score": 4.1 }, "guidance": { "version": 3, "overall": "review" } // see below}Consulte Detección de bots para conocer
el vocabulario de códigos de motivo y qué significa severity.
Campos de multicuenta (Business y superiores). Una vez habilitado el modo persona
en su workspace, el cuerpo lleva además person_id, un bloque reputation (score,
categories, overall_risk), linked_accounts_count y linked_visitors_count: si el
visitante está vinculado a otros visitantes y cuentas. La capa de persona funciona por
ahora en modo de observación y, hasta que entre en producción, estos campos no
aparecen en el cuerpo. No los haga obligatorios en sus esquemas.
guidance lleva recomendaciones listas de «qué hacer» por punto de integración, para
que no tenga que derivar una política a partir de puntuaciones en bruto. Está presente
en cada evento v3 Business+; allow se indica explícitamente:
{ "guidance": { "version": 3, "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 }}Cada escenario empieza en allow y solo puede subir por la escala:
allow → challenge → review → deny. Dentro de un escenario gana el eje más
estricto que se active, y overall es el más estricto de los cuatro escenarios.
| Recomendación | Pago | Registro | Login | Afiliado |
|---|---|---|---|---|
allow | Procéselo | Créela | Déjele entrar | Abone la conversión |
challenge | 3-D Secure / confirmación | Captcha, confirmación por email o móvil | 2FA reforzado, reautenticación | Márquela como dudosa hasta ver actividad |
review | Procéselo, pero póngalo en cola de revisión | Créela con restricciones | Déjele entrar y genere una alerta | Retenga el pago hasta la revisión |
deny | No procese la transacción | Rechace la creación de la cuenta | No le deje entrar | No abone la conversión |
basis enumera los ejes que determinaron la recomendación: un eje cuya propuesta
era más suave que la adoptada no entra en la lista. Léala por código en lugar de
suponer un conjunto fijo:
Eje (basis) | Qué significa |
|---|---|
list | El visitante coincidió con una de las listas de su workspace en modo enforce. Una lista allow anula todos los ejes: cada escenario pasa a allow y basis es exactamente ["list"] |
rule | La visita coincidió con una de las reglas de su workspace en modo enforce; una regla mueve solo la recomendación de su propio escenario (una regla allow suaviza solo ese), y se omite cuando ya actuó una lista |
bot | El detector de bots concluyó que se trata de automatización: deniega todos los escenarios |
risk | La decisión y la puntuación de riesgo global de la visita |
behavior | La biometría del comportamiento dice bot con suficiente confianza: añade fricción en lugar de rechazo |
account_takeover | El comportamiento bajo esta cuenta ya no coincide con el perfil de su titular: login a challenge, pago a review |
network | Tor, o una VPN que sale de un centro de datos |
affiliate_pattern | La forma de las referencias autogeneradas: la conversión de afiliado se retiene como challenge |
fraud_reputation, multiaccounting | La reputación y la agrupación de cuentas de la persona que hay detrás del visitante; aparecen cuando la capa de persona entra en producción |
version es la versión del conjunto de reglas: se incrementa a medida que la lógica
mejora, así que consérvela en sus logs. La versión 2 introdujo el eje list, el
primero que puede suavizar una recomendación; la versión 3 trasladó los umbrales de
login de account_takeover a la escala de la puntuación del veredicto de secuestro de
cuenta, de modo que la misma visita puede recibir deny donde la versión 2 daba
challenge, y al revés.
Guidance es aditivo: los escenarios nuevos llegan como claves nuevas sin romper el
contrato. Gana la fase posterior, salvo en el caso de las recomendaciones
parciales: una entrega calculada sobre un conjunto incompleto de entradas se marca
con "partial": true, y una recomendación parcial no sustituye a una
recomendación completa recibida antes para el mismo request_id. En una entrega
ordinaria el campo partial no aparece en absoluto.
Los umbrales exactos no se documentan deliberadamente. Una recomendación que puede
someterse a ingeniería inversa hasta obtener una puntuación deja de ser una defensa.
Hay exactamente una excepción deliberada: account_assessment.verdict.threshold, la
frontera de decisión del veredicto de secuestro de cuenta descrito más abajo.
account_takeoverSolo Business y Enterprise; en planes inferiores no se crea ninguna entrega, aunque un
webhook esté suscrito a este evento. El cuerpo es el sobre de identificación completo
correspondiente a su plan más un bloque account_alert y el bloque
account_assessment descrito en la sección siguiente, entregado como máximo una vez
por visita:
{ "version": 3, "event": "account_takeover", "event_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31:ato", "request_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31", "phase": "beacon", // la alerta se levanta desde un beacon; solo el event_id dice "ato" "account_alert": { "type": "behavior-drift/2", // kind of alert and the version of its construction "account_id": "user-42", // your linked_id for the account "drift_score": 0.71 // the value the verdict was made on }, "account_assessment": { "type": "behavior-drift/2", "account_id": "user-42", "state": "assessed_alert", "verdict": { "severity": "high", "score": 0.71, "threshold": 0.3565, "scale": "manhattan-normalized", "basis": "ring", "windows": 9 }, "profile": { "windows": 6, "windows_effective": 5, "oldest_window_age_seconds": 1837 } } // …the remaining identification fields}Por qué type lleva una versión. La construcción que hay detrás de la puntuación
ya ha cambiado antes: la escala y la base del veredicto. behavior-drift/2 es la
primera construcción versionada. Si calibró sus propias reglas sobre el número, trate
un cambio de este valor como una señal para revisarlas.
account_alert.drift_score e identification.drift_score son el mismo número
(desde el 2026-10-03): la puntuación de comportamiento suavizada sobre la que se tomó
el veredicto, medida contra el anillo de ventanas de confianza pasadas del titular de
la cuenta. Antes de esa fecha identification.drift_score llevaba una distancia en
bruto en otra escala: no mezcle valores de uno y otro lado de esa fecha. Cuando una
ventana no se evaluó, el campo está ausente en lugar de valer cero. Use
account_assessment.verdict cuando necesite el número junto con el umbral con el que
se comparó.
En v1 el bloque es accountAlert con type, linkedId y drift, y no hay bloque de
evaluación. En v2 la alerta renombra dos campos — linkedId → accountId y drift →
driftScore — y añade accountAssessment; v3 usa los nombres snake_case de arriba.
Actualice su manejador cuando cambie de versión, o su lógica de secuestro de cuenta
dejará de ver los datos en silencio.
account_assessmentSolo Business y Enterprise. Requiere una suscripción explícita: * no lo
incluye.
Sin este evento, la ausencia de una alerta significa dos cosas distintas a la vez: o bien evaluamos la sesión contra el perfil del titular de la cuenta y coincidió, o bien no pudimos evaluarla en absoluto — el perfil del titular no está listo, la ventana era demasiado escasa o el tráfico no era de una persona. Ambas cosas parecen silencio, y el silencio se lee como seguridad. Normalmente no lo es: en un día completo de producción de septiembre de 2026 nos abstuvimos de emitir veredicto en el 73 % de las ventanas y el 80 % de las cuentas. Un proceso construido sobre «sin alerta, está bien» se apoya en un estado que la mayoría de las veces no tenemos.
{ "version": 3, "event": "account_assessment", "event_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31:ato-state-not_assessed", "request_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31", "phase": "beacon", "account_assessment": { "type": "behavior-drift/2", "account_id": "user-42", "state": "not_assessed", // always present, one of three values "reason": "profile_not_ready", // only when state is not_assessed "profile": { "windows": 3, // windows in the owner's reference ring "windows_effective": 2, // of those, how many yielded a distance "oldest_window_age_seconds": 1837 } } // …the remaining identification fields}state nunca está ausente ni vacío:
state | Significado | Qué hacer |
|---|---|---|
assessed_clear | Evaluada; el comportamiento coincide con el titular | Nada |
assessed_alert | Evaluada; el comportamiento diverge | Verificación reforzada (step-up): la alerta account_takeover lleva el mismo veredicto |
not_assessed | No se emitió veredicto | No la trate como limpia; recurra a sus propias señales |
reason (solo con not_assessed):
reason | Significado |
|---|---|
profile_not_ready | La referencia del titular no puede producir por ahora un veredicto para esta cuenta. Trátelo como un estado, no como una etapa: puede no cambiar nunca, así que no espere |
profile_learning | La referencia todavía se está acumulando |
window_too_sparse | Había una persona, pero la ventana contenía demasiado poca interacción |
not_computable | La ventana y la referencia no tenían ejes informativos en común |
bot_traffic | Había datos suficientes, y no había ninguna persona que evaluar |
Desde el 2026-10-04 18:00 UTC, window_too_sparse y not_computable ya no se emiten
para un titular cuya referencia está lista: esa ventana se informa como
profile_not_ready. Los dos motivos siguen en la lista porque las entregas anteriores
los llevan: si su manejador se ramifica según ellos, encamine profile_not_ready de la
misma manera, y no compare las tasas de estos motivos de uno y otro lado de esa fecha.
state y reason no dependen del plan. verdict es Business+, igual que
drift_score.
El bloque verdict está presente solo con assessed_clear y assessed_alert.
Con not_assessed el bloque está ausente en lugar de rellenarse con ceros: un score
de 0 junto a un threshold de 0 se leería como «el comportamiento coincidió
exactamente».
| Campo | Significado |
|---|---|
severity | low o high — dos bandas, deliberadamente: una banda intermedia necesitaría un segundo umbral en la misma escala |
score | El valor sobre el que se tomó el veredicto |
threshold | El valor con el que realmente se comparó |
scale | Cómo se construye la puntuación: manhattan-normalized es d/(1+d) en un espacio de comportamiento normalizado, donde 0 significa coincidencia exacta |
basis | ring — distancia a la más cercana de las ventanas de confianza pasadas del titular; centroid — distancia a su perfil promediado |
windows | Cuántas ventanas se agregaron en la puntuación |
score y threshold están siempre en la misma escala, con nombre, así que el par
reproduce la decisión: la alerta se dispara exactamente cuando score > threshold.
Con qué frecuencia llega. Como máximo una entrega por estado y visita; en la
práctica, una por visita que lleve un linked_id, no una por ventana de
comportamiento. Un estado puede cambiar dentro de una misma visita — por ejemplo, la
referencia termina de aprender y not_assessed pasa a assessed_clear — y entonces
recibe ambas, en orden. Esa transición es posible, no prometida: profile_not_ready
puede persistir durante toda la vida de la cuenta.
Lo que no promete. Las cuentas mejor protegidas son las de usuarios activos con sesiones largas y un perfil de referencia completo; las peor protegidas son las de usuarios poco frecuentes, para quienes un secuestro es más peligroso. Es una propiedad de la construcción, no un umbral que se pueda ajustar. El evento informa de una divergencia de comportamiento respecto a una referencia: no pretende detectar el secuestro de cuentas en general.
attack_detectedLa alerta de pico de bots llega en el sobre v3 común con un bloque attack. No tiene
campos de identificación: es un evento a nivel de workspace:
{ "version": 3, "event": "attack_detected", "event_id": "c0a8e1f2-…", // alert id; matches X-Tracio-Event-Id "timestamp": "2026-07-30T12:00:00Z", "attack": { "kind": "bot_spike", "severity": "critical", // warning | critical "window_minutes": 15, "recent_bots": 4210, "recent_total": 5100, "expected": 180.5 // the baseline expected over a window this size }}Los webhooks con la versión 1 del payload reciben el esquema plano histórico de la alerta, que no cambia.
login_risk, trusted_device_enrolled y trusted_device_revokedEstos tres eventos proceden de sus propias llamadas a la API de riesgo de login
(POST /v2/logins/assess) y a sus dispositivos de confianza. Se entregan solo con una
suscripción explícita por nombre — * no los incluye — y solo a webhooks con la
versión 2 o 3 del payload; la versión 1 no tiene cuerpo para ellos.
login_risk se envía cuando una evaluación devuelve challenge o review, nunca
con allow, deny o not_assessed. Su bloque login_risk es la evaluación
almacenada, exactamente como la dio la respuesta síncrona. Id del evento:
login-risk:<id>, donde <id> es nuestro identificador del registro almacenado;
tome su propio assessment_id del cuerpo.trusted_device_enrolled y trusted_device_revoked se envían en cada alta,
renovación y revocación de un dispositivo de confianza. Su bloque trusted_device
— user_id, device_ref, enrolled_at, expires_at, revoked_at, revoked_by
(api o dashboard) — es una instantánea del momento del evento; con
trusted_device_enrolled, revoked_at y revoked_by son null. Id del evento:
trusted-device:<n>.Se envían de forma asíncrona, hasta unos cinco segundos después de la llamada, y no
llevan el encabezado X-Tracio-Request-Id: use login_risk.request_id para encontrar
la visita. El webhook es una notificación para auditoría y alertas; la decisión en sí
es la respuesta síncrona.
{ "version": 3, "event": "login_risk", "event_id": "login-risk:4b1f9e2c-6d3a-4f80-9b7e-2a5c8d1e0f37", "timestamp": "2026-10-17T10:00:00Z", "login_risk": { "assessment_id": "snap-1", "user_id": "alice", "state": "assessed", "recommendation": "challenge", "reasons": ["new_device"] // …the rest of the assessment }}{ "version": 3, "event": "trusted_device_revoked", "event_id": "trusted-device:7", "timestamp": "2026-10-17T11:00:00Z", "trusted_device": { "user_id": "alice", "device_ref": "7978151c54e94838", "enrolled_at": "2026-10-17T10:00:00Z", "expires_at": "2026-11-16T10:00:00Z", "revoked_at": "2026-10-17T11:00:00Z", "revoked_by": "dashboard" }}affiliate_threshold_crossedSe entrega solo con una suscripción explícita por nombre — * no lo incluye — y
solo a webhooks con la versión 2 o 3 del payload. Cada 15 minutos TRACIO recalcula la
puntuación de calidad de cada afiliado con datos suficientes y envía el evento cuando
su recomendación empeora: none → review, none → hold o review → hold. Una mejora
no envía nada y permite que el siguiente empeoramiento se vuelva a notificar. El evento
pertenece al workspace: va a los webhooks suscritos de todos los entornos y no lleva
el encabezado X-Tracio-Request-Id. Id del evento:
affiliate-threshold:<affiliate_id>:<recommendation>:<unix time>.
{ "version": 3, "event": "affiliate_threshold_crossed", "event_id": "affiliate-threshold:aff_17:review:1792490400", "timestamp": "2026-10-20T10:00:00Z", "affiliate_threshold": { "affiliate_id": "aff_17", "recommendation": "review", // none | review | hold "previous_recommendation": "none", "quality_score": 72, // 0..100, higher is better "hold_days": 14, // the current hold period of the workspace "crossed_at": "2026-10-20T10:00:00Z", "metrics": { "reg_to_ftd": 0.31, "active14_share": 0.42, "dup_device_share": 0.3, "dup_person_share": 0.1, "ring_share": 0.05, "bonus_hunter_share": 0.2, "dc_vpn_bot_share": 0.1, "chargeback_share": 0.03, "affiliate_fraud_share": 0, "no_visit_share": 0.05 } }}metrics son las proporciones del afiliado en los últimos 90 días, las mismas que
muestra el informe del panel: la proporción de registros que llegaron a un primer
depósito (reg_to_ftd), la proporción de jugadores aún activos 14 días después del
registro (active14_share) y las proporciones de conversiones con un dispositivo o una
persona duplicados, procedentes de una red de fraude, de cazadores de bonos, de un
centro de datos, VPN o bot, etiquetadas como chargeback o como fraude de afiliado, y
sin una visita encontrada. TRACIO solo recomienda: la retención en sí y cualquier
decisión de pago quedan en su plataforma de afiliados. Con la versión 2 del payload el
mismo cuerpo tiene claves camelCase: el bloque es affiliateThreshold, con
affiliateId, previousRecommendation, qualityScore, etc.
transaction_state_changedBusiness y superiores. Se envía cuando cambia el resultado de una transacción que
envió a POST /v2/transactions: las reglas decidieron REVIEW o DECLINE (un
APPROVE no envía nada), un analista envió la transacción a revisión en el panel, o
se estableció, sustituyó o eliminó una etiqueta. Úselo para retener un bono mientras
una solicitud está en revisión y para denegarlo o liberarlo una vez resuelto el
resultado, sin sondeo. * incluye este evento; se entrega solo a webhooks con la
versión 2 o 3 del payload. Un webhook vinculado a un entorno lo recibe solo para ese
entorno.
{ "version": 3, "event": "transaction_state_changed", "event_id": "txn-state:7d1c2b3a-0000-4000-8000-000000000042:118", "timestamp": "2026-10-15T10:04:00Z", "transaction": { "id": "7d1c2b3a-0000-4000-8000-000000000042", "transaction_id": "bonus-claim-1842", "state": "REVIEW", // always the decision of the rules "fraud_score": 50, "effective_state": "DECLINE", // the outcome to act on "recommendations": ["withhold_bonus"], "label": "fraud_detection_bonus_abuse", "label_source": "api", // api | dashboard "label_at": "2026-10-15T10:04:00Z", "previous_effective_state": "REVIEW" // …applied_rules and evidence, as in the transaction response }}| Clave | Significado |
|---|---|
effective_state | El resultado según el que actuar: el estado del analista o de la etiqueta cuando hay uno establecido; si no, state |
recommendations | Qué hacer con el bono, derivado de effective_state |
label, label_source, label_at | La etiqueta actual, dónde se estableció (api o dashboard) y cuándo; las tres son null cuando la transacción no tiene etiqueta |
previous_effective_state | effective_state antes de este cambio; null para el evento enviado con la decisión automática |
El bloque muestra la transacción tal como está cuando se envía el evento: si dos
cambios se suceden rápidamente, ambos eventos llevan el estado más reciente, cada uno
con su propio previous_effective_state y timestamp. El orden no está
garantizado: ordene por timestamp y lea la transacción a través de la API para
conocer su estado actual. Id del evento: txn-state:<id>:created para la decisión
automática y txn-state:<id>:<n> para cada cambio posterior. El evento no dice quién
estableció una etiqueta, solo de dónde procede.
reputation_changedBusiness y superiores. Se envía cuando la reputación entre clientes de una persona que
su organización ha visto pasa a otra banda (clean → suspicious, por ejemplo).
Requiere la capa de persona, que por ahora funciona en modo de observación, así que el
evento solo se dispara en los workspaces donde está habilitada la resolución de
identidad entre dispositivos. Es un evento a nivel de persona: no tiene request_id ni
bloques de visita.
{ "version": 3, "event": "reputation_changed", "event_id": "person-reputation:pn_4f2a…:clean->suspicious:2026-07-30T12:10:00.123456Z", "timestamp": "2026-07-30T12:10:00Z", "reputation_change": { "person_id": "pn_4f2a…", "score": 46, "band": "suspicious", // clean | suspicious | fake "previous_band": "clean", "categories": ["chargeback"], "visitor_ids": ["X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"], // the person's visitors in YOUR data "linked_accounts_count": 4 // omitted when zero }}La clave del bloque es reputation_change, no reputation: esta última la ocupa la
reputación en el contexto de una visita concreta, y son cosas distintas. El esquema 1
entrega la forma plana histórica: los mismos campos en el nivel superior.
Cada entrega incluye un encabezado X-Tracio-Signature:
X-Tracio-Signature: t=1710432000,v1=5257a869e7ecebed…t es la marca de tiempo Unix (en segundos) en que se firmó la petición.v1 es el HMAC-SHA256 codificado en hexadecimal de "<t>.<rawRequestBody>", con su
secreto de webhook como clave.La marca de tiempo forma parte del contenido firmado, lo que aporta protección frente a replay.
Dos cosas que debe hacer bien, o la verificación fallará en producción:
v1=. Durante una rotación del
secreto, el encabezado lleva dos firmas, y un parser que conserve solo una de
ellas rechazará entregas válidas durante toda la ventana de rotación.// Express.js exampleimport 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.visitor_id}`) console.log(`Bot: ${event.bot?.result}`) // "human" | "bot" | "uncertain"
res.status(200).send("OK")})Las entregas con esquema 2 y 3 llevan además X-Tracio-Signature-Ed25519
(t=<unix>,kid=<id>,v1=<base64>). Ambas partes conocen el secreto HMAC, así que el
HMAC demuestra que quien envía conoce el secreto, pero no que la petición se origine
en TRACIO; la firma asimétrica sí. Las claves públicas se publican en
https://api.tracio.ai/.well-known/webhook-keys, indexadas por kid: lea el campo
public_key. El alias heredado publicKey lleva el mismo valor y se retirará el
2027-04-12.
Las entregas de prueba enviadas desde el panel se firman solo con HMAC: la clave
privada de plataforma vive en los nodos de entrega y deliberadamente no está
disponible para el panel. Un verificador que exija Ed25519 de forma estricta debe
dejar pasar las entregas de prueba (llevan el sufijo :test en event_id); de lo
contrario, las pruebas desde el panel fallan mientras producción está sana. La misma
precaución vale para las comprobaciones de formato: una entrega de prueba lleva el
request_id con la forma test_<hex> y el literal test_visitor como visitor_id,
de modo que un manejador que los valide contra las formas de producción rechazará una
entrega que por lo demás está bien formada.
Tras una rotación, ambos secretos siguen siendo válidos durante 24 horas y el encabezado lleva las dos firmas, de modo que puede actualizar su configuración sin perder entregas. La acción Revoke now acorta la ventana. Actualice el secreto de su lado dentro de esas 24 horas: cuando la ventana se cierra, el secreto antiguo deja de coincidir, y si su endpoint responde a una firma no válida con un 4xx, cinco respuestas así seguidas desactivan el webhook.
| Encabezado | Descripción |
|---|---|
Content-Type | application/json |
X-Tracio-Signature | t=<unix>,v1=<hmac_sha256_hex> — dos v1= durante una ventana de rotación |
X-Tracio-Signature-Ed25519 | Firma de plataforma, t=<unix>,kid=<id>,v1=<base64> (solo v2 y v3) |
X-Tracio-Event-Id | Identificador de la entrega — la clave de idempotencia |
X-Tracio-Request-Id | Identificador de la visita, coincide con request_id (solo v2 y v3). Se envía solo para eventos de visita — identification, account_takeover y account_assessment |
X-Tracio-Event-Type | El tipo de evento (solo v2 y v3) |
X-Tracio-Delivery-Attempt | Número de intento, empezando en 1 (solo v2 y v3) |
X-Tracio-Payload-Version | 3 o 2 (solo v2 y v3) |
X-Tracio-Webhook-Id | Identificador del webhook que produjo esta entrega |
Las entregas pueden reintentarse, y un reintento lleva el mismo
X-Tracio-Event-Id. Deduplique por él:
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")})Tenga en cuenta que event_id es único por evento, no por webhook: si varios
webhooks del workspace están suscritos al mismo evento, cada uno recibe una entrega
con el mismo identificador. Para identification se construye como
<request_id>:<phase>, y por eso las tres fases de una visita se deduplican de forma
independiente en lugar de fundirse en una. Los eventos sin visita tienen sus propias
formas: consulte cada evento más arriba.
Responda con 2xx: es la única señal de que una entrega ha sido aceptada.
| Respuesta | Qué ocurre |
|---|---|
2xx | Entrega completada |
429 Too Many Requests | No cuenta como fallo ni gasta un intento; se respeta un Retry-After más largo |
408, 425, 5xx, conexión cortada | Se reintenta con una pausa creciente |
410 Gone | El endpoint se considera eliminado — el webhook se desactiva de inmediato |
Otros 4xx | Se reintenta, pero cinco seguidos desactivan el webhook — 400/401/404 no se curan reintentando |
Calendario de reintentos: 5 s → 30 s → 2 min → 10 min → 30 min → 2 h → 6 h (8 intentos). Los primeros reintentos caben dentro de un minuto, así que un reinicio breve de su servicio no le cuesta una notificación. Cada pausa se aleatoriza entre la mitad y el valor completo para que los reintentos no se disparen todos a la vez tras una caída.
La desactivación automática requiere a la vez un umbral (20 fallos consecutivos, o 5 errores de configuración) y al menos 15 minutos consecutivos de fallos: un reinicio breve no puede matar la integración, ni siquiera con muchas entregas en cola. Un intervalo de más de 15 minutos reinicia la cuenta. El panel muestra el motivo, con el código de respuesta y el texto del error, y un botón Re-enable que pone los contadores a cero.
| Plan | Webhooks por workspace |
|---|---|
| Free | No disponible |
| Pro | 5 |
| Business | 20 |
| Enterprise | 100 |
Los endpoints deben ser https con IP pública —las direcciones privadas y de loopback
se rechazan, también en una redirección— y no encadenar más de dos redirecciones.
Solo se siguen las redirecciones 307 y 308. 301, 302 y 303 indican al
cliente que cambie a GET y descarte el cuerpo, así que una entrega no las sigue y el
intento cuenta como fallido. Si su balanceador de carga normaliza la URL (añadiendo
www o una barra final), apunte el webhook directamente a la URL final.
Los webhooks se gestionan en el panel. El panel se apoya en una API de gestión con
alcance de workspace, servida en el host de la aplicación (por ejemplo
https://app.tracio.ai/api/v1), y los endpoints de abajo son justo los que llama.
Todos los endpoints de webhook viven bajo /workspaces/{wsId}.
Esta no es una superficie servidor a servidor. La API de gestión solo acepta el JWT de su sesión del panel, verificado contra su rol de workspace (RBAC); aquí se rechaza una clave secreta
tracio_sk_…. Como esa sesión vive en el navegador y caduca con él, tome las llamadas de abajo como una descripción de lo que hace el panel y no como una integración que automatizar. Para el acceso programático desde su propio backend, use la Data API de solo lectura.
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": [] }'El secreto de firma lo genera TRACIO y se devuelve una sola vez en la creación (y
en la rotación) bajo signingSecret. Guárdelo de forma segura: es la clave que usa
para verificar las firmas.
{ "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" }}En lecturas posteriores el signingSecret aparece enmascarado (null): solo lo
revelan la creación y la rotación del secreto.
| Método | Ruta | Descripción |
|---|---|---|
GET | /workspaces/{wsId}/webhooks | Listar webhooks |
PATCH | /workspaces/{wsId}/webhooks/{webhookId} | Actualizar url / events / status |
DELETE | /workspaces/{wsId}/webhooks/{webhookId} | Eliminar un webhook |
POST | /workspaces/{wsId}/webhooks/{webhookId}/test | Enviar una entrega de prueba firmada |
POST | /workspaces/{wsId}/webhooks/{webhookId}/secret/rotate | Rotar el secreto de firma |
GET | /workspaces/{wsId}/webhooks/{webhookId}/deliveries | Listar los intentos de entrega recientes |
Devuelva un 2xx lo antes posible y procese el payload de forma asíncrona para evitar
timeouts:
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?.risk_score > 50) { await alertFraudTeam(event) }
if (event.bot?.result === "bot") { await blockVisitor(event.visitor_id) }}Use la acción Test de un webhook (o POST .../webhooks/{webhookId}/test) para
enviar un payload de ejemplo firmado a su endpoint y confirmar que es alcanzable y que
verifica las firmas correctamente.
Para el desarrollo local, exponga su servidor con un túnel como ngrok:
ngrok http 3000# Use the generated URL as your webhook endpoint