Webhook Callback

PrivateID will send a POST request to the callback URL when the verification session completes.

Operations That Send Webhooks

Webhooks are sent for the following PrivateID operations:

• REGISTER/ENROLL - User enrollment with biometric capture
• SIGN-IN - Facial recognition authentication
• VERIFY - User verification operations

All webhook responses follow the same structure and may include browser security indicators when browser data is available from the session.

Example Webhook Response:

{
  "sessionId": "ed36ca71-c1e0-4eaa-a517-a405bc111077",
  "status": "SUCCESS",
  "puid": "NLOaU9FP-RvN7-TAmR-jR9T-nKt75q9L20ad",
  "guid": "wbvH0V3u-tntc-XjWO-Cr8F-ygZHXi6rpu3d",
  "identityInformation": {
    "documentType": "drivers_license",
    "verificationDate": "1743795933839"
  },
  "contactInformation": {
    "email": "test@test.com",
    "phone": "1111111111"
  },
  "message": "here will be the message",
  "indicators": {
    "headless": {
      "webdriver": false,        // WebDriver automation detection (Selenium, Puppeteer)
      "userAgent": false,        // Suspicious/modified user agent strings
      "webGL": false,           // Missing/inconsistent WebGL rendering
      "phantom": false,         // PhantomJS headless browser detection
      "selenium": false,        // Selenium automation framework detection
      "chrome": false,          // Chrome automation flags/properties
      "permissions": false,     // Unusual permission states in headless mode
      "plugins": false,         // Missing/suspicious plugin configurations
      "languages": false,       // Inconsistent language settings
      "webRTC": false,          // WebRTC availability inconsistencies
      "notification": false,    // Notification API availability issues
      "deviceMemory": false,    // Suspicious device memory reporting
      "connectionType": false,  // Unusual network connection reporting
      "timing": false          // Suspicious timing patterns vs human behavior
    },
    "virtualCamera": {
      "virtualCameraSoftware": false,  // OBS, ManyCam, XSplit detection
      "suspiciousLabels": false,       // Fake camera device names/labels
      "noMediaDevices": false,         // No physical media devices present
      "mediaDevicesError": false       // Media device enumeration errors
    },
    "browserAnomalies": {
      "missingWebAPIs": false,         // Standard web APIs not present
      "inconsistentFingerprint": false, // Browser fingerprint mismatches
      "automationProperties": false    // Non-WebDriver automation artifacts
    }
  }
}

Response Fields

Browser Security Indicators

The indicators field provides comprehensive browser security analysis to help detect fraud attempts and automated verification tools. This field is optional and only included when browser data exists from the verification session.

Indicator Categories

Headless Detection (headless)

Detects automated browsers and headless tools commonly used in bot traffic and automated verification attempts.

Virtual Camera Detection (virtualCamera)

Identifies fake camera software and suspicious video sources to prevent spoofed identity verification using fake video feeds.

Browser Anomaly Detection (browserAnomalies)

Detects inconsistent browser environments, tampered browsers, or unusual configurations.

Value Interpretation

• true: Suspicious activity detected for this indicator
• false: No suspicious activity detected for this indicator
• Each indicator is independent and can be evaluated separately

Implementation Notes

• Availability: Field is optional and only included when browser data exists from the verification session
• Operations: Available in webhooks for REGISTER/ENROLL, SIGN-IN, and VERIFY operations
• Data Source: Sourced from the most recent usage log and browser analysis for the verification session
• Session Dependency: Only present when the user completed verification through a web browser (not available for API-only integrations)
• Backward Compatibility: Existing integrations will continue to work unchanged - new field is purely additive

Security Recommendations

Risk Assessment

• Higher true counts across indicators suggest higher fraud risk
• Consider implementing scoring thresholds based on your risk tolerance
• Different indicator categories may have varying significance for your use case

Best Practices

• Combine with other signals: Use indicators alongside other verification data for comprehensive fraud detection
• Pattern analysis: Log indicator patterns over time to identify emerging fraud trends
• Threshold tuning: Adjust risk thresholds based on your specific security requirements
• Category weighting: Consider weighting different indicator categories based on their relevance to your risk model

Example Risk Scoring

// Example risk calculation
function calculateRiskScore(indicators) {
  let score = 0;
  
  // Weight headless indicators heavily
  Object.values(indicators.headless).forEach(value => {
    if (value) score += 2;
  });
  
  // Weight virtual camera indicators very heavily
  Object.values(indicators.virtualCamera).forEach(value => {
    if (value) score += 3;
  });
  
  // Weight browser anomalies moderately
  Object.values(indicators.browserAnomalies).forEach(value => {
    if (value) score += 1;
  });
  
  return score;
}

// Usage
const riskScore = calculateRiskScore(webhookData.indicators);
const isHighRisk = riskScore > 10; // Adjust threshold as needed

High-Risk Example Response

{
  "sessionId": "ed36ca71-c1e0-4eaa-a517-a405bc111077",
  "status": "SUCCESS",
  "puid": "NLOaU9FP-RvN7-TAmR-jR9T-nKt75q9L20ad",
  "guid": "wbvH0V3u-tntc-XjWO-Cr8F-ygZHXi6rpu3d",
  "identityInformation": {
    "documentType": "drivers_license",
    "verificationDate": "1743795933839"
  },
  "contactInformation": {
    "email": "test@test.com",
    "phone": "1111111111"
  },
  "message": "Verification completed with security warnings",
  "indicators": {
    "headless": {
      "webdriver": true,
      "userAgent": true,
      "webGL": false,
      "phantom": false,
      "selenium": true,
      "chrome": true,
      "permissions": false,
      "plugins": true,
      "languages": false,
      "webRTC": false,
      "notification": false,
      "deviceMemory": false,
      "connectionType": false,
      "timing": true
    },
    "virtualCamera": {
      "virtualCameraSoftware": true,
      "suspiciousLabels": true,
      "noMediaDevices": false,
      "mediaDevicesError": false
    },
    "browserAnomalies": {
      "missingWebAPIs": true,
      "inconsistentFingerprint": true,
      "automationProperties": true
    }
  }
}

Detailed Indicator Reference

Headless Detection Indicators

webdriver

Detection Target: WebDriver automation tools (Selenium, Puppeteer, Playwright) How it Works: Checks for automation properties like:

• window.webdriver or navigator.webdriver properties
• ChromeDriver-specific properties (window.chrome.runtime in non-extension contexts)
• WebDriver command executor endpoints
• Automation-specific window properties Risk Level: High - Direct evidence of automation tools

userAgent

Detection Target: Modified or suspicious user agent strings How it Works: Analyzes user agent strings for:

• Headless browser signatures ("HeadlessChrome", "PhantomJS")
• Automation tool signatures ("Selenium", "WebDriver")
• Inconsistencies with other browser properties
• Non-standard or malformed user agent patterns Risk Level: Medium - May indicate spoofing attempts

webGL

Detection Target: Missing or inconsistent WebGL capabilities How it Works: Tests WebGL rendering by:

• Checking for null WebGL contexts
• Detecting software rendering signatures
• Analyzing GPU vendor/renderer strings
• Testing WebGL extension availability Risk Level: Medium - Headless browsers often lack proper GPU rendering

phantom

Detection Target: PhantomJS headless browser How it Works: Looks for PhantomJS-specific properties:

• window._phantom object
• callPhantom function
• PhantomJS-specific user agent strings
• PhantomJS runtime properties Risk Level: High - PhantomJS is primarily used for automation

selenium

Detection Target: Selenium automation framework How it Works: Detects Selenium-specific artifacts:

• window.selenium properties
• document.$cdc_ properties (Chrome)
• Selenium WebDriver command executor
• Selenium-specific DOM mutations Risk Level: High - Direct evidence of Selenium automation

chrome

Detection Target: Chrome automation flags and properties How it Works: Checks for Chrome automation indicators:

• --enable-automation flag effects
• --disable-blink-features impacts
• Chrome DevTools Protocol signatures
• Automation-specific Chrome properties Risk Level: High - Chrome-specific automation indicators

permissions

Detection Target: Unusual permission states in headless environments How it Works: Analyzes permission API responses:

• Notification permissions (always denied in headless)
• Geolocation permissions inconsistencies
• Camera/microphone permission anomalies
• Permission query response patterns Risk Level: Medium - Headless browsers have different permission defaults

plugins

Detection Target: Missing or suspicious plugin configurations How it Works: Examines browser plugins:

• Plugin enumeration (navigator.plugins)
• Expected plugins missing (PDF viewer, Flash)
• Suspicious plugin names or descriptions
• Plugin functionality testing Risk Level: Medium - Headless browsers typically have no plugins

languages

Detection Target: Inconsistent language settings How it Works: Compares language properties:

• navigator.language vs navigator.languages
• Language vs browser locale inconsistencies
• Accept-Language header mismatches
• Timezone vs language geographic inconsistencies Risk Level: Low - May indicate spoofed environments

webRTC

Detection Target: WebRTC availability inconsistencies How it Works: Tests WebRTC functionality:

• RTCPeerConnection availability
• Media device enumeration capabilities
• WebRTC API response patterns
• STUN/TURN connectivity testing Risk Level: Medium - Some automation tools disable WebRTC

notification

Detection Target: Notification API availability issues How it Works: Tests notification capabilities:

• Notification API availability
• Permission state consistency
• Notification display capabilities
• Service worker notification support Risk Level: Low - Headless browsers may have limited notification support

deviceMemory

Detection Target: Suspicious device memory reporting How it Works: Analyzes navigator.deviceMemory:

• Unusual memory values (very low/high)
• Missing deviceMemory property
• Inconsistency with other device properties
• Memory value patterns in automation tools Risk Level: Low - Some automation tools report unusual values

connectionType

Detection Target: Unusual network connection reporting How it Works: Examines navigator.connection:

• Missing connection information
• Unusual connection type values
• Bandwidth reporting inconsistencies
• Connection state change patterns Risk Level: Low - Headless environments may have different network reporting

timing

Detection Target: Suspicious timing patterns vs human behavior How it Works: Analyzes interaction timings:

• Page load timing patterns
• Script execution speed
• User interaction timing (clicks, moves)
• Navigation timing inconsistencies Risk Level: Medium - Automation tools often have non-human timing patterns

Virtual Camera Detection Indicators

virtualCameraSoftware

Detection Target: Virtual camera applications (OBS, ManyCam, XSplit, etc.) How it Works: Analyzes camera device properties:

• Device labels containing "Virtual", "OBS", "ManyCam"
• Driver names indicating software cameras
• Device capability patterns of virtual cameras
• Video stream metadata analysis Risk Level: Very High - Direct evidence of video spoofing tools

suspiciousLabels

Detection Target: Fake camera device names/labels How it Works: Examines media device labels:

• Non-hardware camera names ("Screen Capture", "Virtual Camera")
• Software application names in device labels
• Generic or suspicious device descriptions
• Pattern matching against known virtual camera names Risk Level: High - Indicates attempt to use non-physical video sources

noMediaDevices

Detection Target: Environments with no physical media devices How it Works: Checks for complete absence of:

• Video input devices
• Audio input devices
• Physical camera hardware
• Media device enumeration returning empty results Risk Level: Medium - May indicate VM or specially configured environments

mediaDevicesError

Detection Target: Media device enumeration errors How it Works: Detects errors in:

• navigator.mediaDevices.enumerateDevices() calls
• Permission errors during device access
• Unusual device access patterns
• Device API response inconsistencies Risk Level: Medium - May indicate tampered media device APIs

Browser Anomaly Detection Indicators

missingWebAPIs

Detection Target: Standard web APIs not present How it Works: Tests for missing standard APIs:

• navigator.mediaDevices availability
• navigator.geolocation presence
• window.crypto and WebCrypto APIs
• Storage APIs (localStorage, sessionStorage)
• Modern web APIs expected in current browsers Risk Level: Medium - May indicate modified or headless environments

inconsistentFingerprint

Detection Target: Browser fingerprint mismatches How it Works: Cross-references browser properties:

• Screen resolution vs reported display properties
• Timezone vs language geographic consistency
• User agent vs actual browser capabilities
• Hardware vs software rendering mismatches Risk Level: Medium - May indicate spoofed or modified environments

automationProperties

Detection Target: Non-WebDriver automation artifacts How it Works: Detects other automation indicators:

• Modified JavaScript prototypes
• Injected automation scripts
• Unusual window properties
• DOM manipulation patterns
• Non-standard event handling Risk Level: High - Evidence of browser manipulation or automation