Skip to main content

​
Identifiers

ShieldLabs uses four identifiers in every webhook payload. Each tracks a different dimension of the user session.

​
RequestID

550e8400-e29b-41d4-a716-446655440000
Type: UUID v4
Scope: Single check The RequestID identifies one specific fingerprint submission. Every call to checkAnonymous() or checkAuthenticatedUser() generates a new RequestID. Use RequestID to:
  • Correlate the browser callback with the incoming webhook
  • Look up a specific session in the dashboard
  • Query historical data via the pub API
// Browser
mod.checkAuthenticatedUser(userId, (ip, requestId) => {
  // Pass requestId to your server
  fetch('/api/track', {
    method: 'POST',
    body: JSON.stringify({ shieldRequestId: requestId }),
  });
});

​
DeviceID

a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
Type: 32-character hex string
Scope: Device (hardware + software fingerprint) The DeviceID is a MurmurHash3 x64 128-bit hash of 30+ browser parameters: canvas, WebGL, fonts, audio, screen, platform, and more.
  • Stable across browser sessions for the same device
  • Changes if hardware changes significantly (GPU, screen) or browser profile is reset
  • Anti-detect browsers often cycle DeviceIDs
Use DeviceID to:
  • Detect the same physical device across multiple accounts (multi-accounting)
  • Rate-limit by device rather than IP or user
  • Identify devices that have been banned

​
VisitorID

7f3e9a12-4b5c-4d6e-8f9a-0b1c2d3e4f5a
Type: UUID
Scope: Browser profile (localStorage) The VisitorID is stored in localStorage and persists across browser sessions on the same device/profile. It identifies a persistent visitor.
  • Survives page refreshes and browser restarts
  • Cleared when the user clears localStorage
  • Different browser profiles on the same device have different VisitorIDs
  • Private/incognito mode generates a new VisitorID each session
Use VisitorID to:
  • Track returning visitors across sessions
  • Detect users who create multiple accounts with the same browser profile
  • Build a history of risk scores for a visitor over time

​
UserHID

e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
Type: String (typically SHA-256 hex, 64 chars)
Scope: Authenticated user The UserHID is the value you pass to checkAuthenticatedUser(). It should be a stable, hashed identifier for the user — never the raw user ID or email.
  • "anonymous" when checkAnonymous() is used
  • Lets you query all sessions for a specific user via the pub API
// Use Web Crypto to hash
async function hashUserId(id) {
  const buf = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(String(id)));
  return Array.from(new Uint8Array(buf)).map(b => b.toString(16).padStart(2, '0')).join('');
}

​
Summary

IdentifierTracksChanges whenExample use
RequestIDSingle checkEvery checkCorrelate webhook with browser event
DeviceIDHardware fingerprintHardware/browser profile changesMulti-accounting, device bans
VisitorIDBrowser profilelocalStorage clearedReturning visitor history
UserHIDYour userYou pass a different valuePer-user risk history

​
Querying by identifier

Use the pub API to look up sessions by any identifier: 
# By UserHID
GET /pub/{public_key}/{secret_key}/history/user_hid/{hashed_user_id}

# By DeviceID
GET /pub/{public_key}/{secret_key}/history/device_id/{device_id}

# By VisitorID
GET /pub/{public_key}/{secret_key}/history/visitor_id/{visitor_id}
See API Reference — History for full details.