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:

Sample Webhook Payload

{
  "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",
  "errors": [
    {
      "code": 1,
      "message": "Image spoof"
    }
  ],
  "images": [
    {
      "type": "portrait",
      "data": "base64EncodedImageData..."
    }
  ],
  "indicators": {
    "headless": {
      "webdriver": false,
      "userAgent": false,
      "webGL": false,
      "phantom": false,
      "selenium": false,
      "chrome": false,
      "permissions": false,
      "plugins": false,
      "languages": false,
      "webRTC": false,
      "notification": false,
      "deviceMemory": false,
      "connectionType": false,
      "timing": false
    },
    "virtualCamera": {
      "virtualCameraSoftware": false,
      "suspiciousLabels": false,
      "noMediaDevices": false,
      "mediaDevicesError": false
    },
    "browserAnomalies": {
      "missingWebAPIs": false,
      "inconsistentFingerprint": false,
      "automationProperties": false
    }
  },
  "riskEvaluation": {
    "score": 0,
    "level": "LOW",
    "recommendation": "ALLOW",
    "flags": [],
    "signals": {
      "behavioral": null,
      "browser": {
        "score": 0,
        "flags": []
      }
    }
  }
}

Response Fields

Name
sessionId
Description
Unique identifier for the verification session.
Name
status
Description
"SUCCESS" if verification is successful, "FAILED" if verification failed.
Name
puid
Description
Private User Identifier - unique identifier for the verified user.
Name
guid
Description
Global Unique Identifier for the verification session.
Name
identityInformation
Description
Contains document type and verification timestamp.
Name
contactInformation
Description
User's email and phone contact details.
Name
message
Description
Additional status or error message.
Name
errors
Description
(Optional) Array of error objects containing error codes and their corresponding messages. Each error object includes a code (number) and message (string) describing what went wrong during verification.
Name
images
Description
(Optional) Array of image objects containing captured user images. Only present when sendImages: true is configured in the session request. Each image object includes a type (e.g., "portrait", "document") and data (base64-encoded image string).
Name
indicators
Description
(Optional) Raw browser signal data. Contains boolean flags per detection category. Only present when browser data is available from the verification session.
Name
riskEvaluation
Description
Computed risk assessment derived from browser and behavioral signals. Provides an actionable recommendation alongside a per-source score breakdown. Present whenever browser data is available.

The indicators field provides raw browser signal data for advanced clients who need access to individual detection flags. Each boolean flag is true when suspicious activity is detected for that signal, false otherwise. This field is optional and only present when browser data is available from the session.

For most integrations, use riskEvaluation instead — it provides a computed verdict based on these signals without requiring you to implement your own scoring logic.

Indicator Categories

Headless Detection (`headless`)

Boolean flags indicating signs of automated or headless browser usage.

Name
webdriver
Description
Detected WebDriver automation (e.g. Selenium, Puppeteer).
Name
userAgent
Description
Suspicious or inconsistent user agent string.
Name
webGL
Description
Missing or inconsistent WebGL rendering capabilities.
Name
phantom
Description
PhantomJS headless browser detected.
Name
selenium
Description
Selenium automation framework detected.
Name
chrome
Description
Chrome automation flags or properties detected.
Name
permissions
Description
Unusual browser permission states detected.
Name
plugins
Description
Missing or suspicious browser plugin configuration.
Name
languages
Description
Inconsistent language or locale settings.
Name
webRTC
Description
WebRTC availability inconsistency detected.
Name
notification
Description
Notification API availability issue detected.
Name
deviceMemory
Description
Suspicious device memory value reported.
Name
connectionType
Description
Unusual network connection type reported.
Name
timing
Description
Suspicious interaction timing patterns detected.

Virtual Camera Detection (`virtualCamera`)

Boolean flags indicating the presence of fake or software-based camera sources.

Name
virtualCameraSoftware
Description
Virtual camera software detected on the device.
Name
suspiciousLabels
Description
Camera device has a suspicious or non-hardware label.
Name
noMediaDevices
Description
No physical media devices detected.
Name
mediaDevicesError
Description
Error encountered during media device enumeration.

Browser Anomaly Detection (`browserAnomalies`)

Boolean flags indicating inconsistent or tampered browser environments.

Name
missingWebAPIs
Description
Standard browser APIs are absent or disabled.
Name
inconsistentFingerprint
Description
Browser fingerprint properties are inconsistent with each other.
Name
automationProperties
Description
Non-WebDriver automation artifacts detected.

Notes

Available for REGISTER/ENROLL, SIGN-IN, and VERIFY operations
Only present when the session was completed through a web browser
Sourced from the most recent usage log for the session

Risk Evaluation

The riskEvaluation field is the primary field for access control decisions. It provides a computed verdict based on browser and behavioral signals without requiring you to implement scoring logic yourself.

Name
score
Type
number
Description
Composite risk score from 0–100.
Name
level
Type
LOW | MEDIUM | HIGH | CRITICAL
Description
Risk tier derived from the score.
Name
recommendation
Type
ALLOW | REVIEW | BLOCK
Description
Suggested action: ALLOW = proceed normally, REVIEW = flag for manual review, BLOCK = deny access.
Name
flags
Type
string[]
Description
List of short flag codes identifying what contributed to the score. Look up each code in the Flag Code Reference below.
Name
signals
Type
object
Description
Per-source breakdown of what drove the score.
- Name
  behavioral
  Type
  object | null
  Description
  Risk contribution from session behavioral analysis. Contains score and flags. Null when not applicable to the operation type.
- Name
  browser
  Type
  object | null
  Description
  Risk contribution from browser environment analysis. Contains score and flags.

Acting on `recommendation`

const { recommendation, flags } = webhookData.riskEvaluation;

if (recommendation === 'BLOCK') {
  // Deny access
} else if (recommendation === 'REVIEW') {
  // Flag for manual review — check flags[] for context
} else {
  // ALLOW — proceed normally
}

Best Practices

Use recommendation as your primary signal — it already accounts for signal weighting and combinations
Log flags for audit trails — flag codes are stable identifiers suitable for alerting and compliance queues
Use signals for triage — signals.browser vs signals.behavioral tells you which category to investigate
Use indicators for deeper investigation — raw browser signal data is available if you need to inspect individual signals

Flag Code Reference

Flags are returned as short codes. Each code maps to a category and a description.

Behavioral (B)

Code	Description
`B001`	No usage logs received for this session
`B002`	Face scan logs arrived after result was submitted
`B003`	No face scan activity recorded before result submission
`B004`	Result submitted too fast after face scan page loaded

Behavioral flags are only present on age estimation sessions.

Browser / API Integrity (BR)

Code	Description
`BR001`	Browser API tampered
`BR002`	getUserMedia API overridden
`BR003`	MediaStreamTrack API overridden
`BR004`	enumerateDevices API overridden
`BR005`	Permissions query API overridden
`BR006`	Function toString tampered
`BR007`	Property descriptor anomaly
`BR008`	Automation properties detected
`BR009`	Inconsistent browser fingerprint
`BR010`	Standard browser APIs missing

Virtual Camera (VC)

Code	Description
`VC001`	Virtual camera detected (critical confidence)
`VC002`	Virtual camera detected (high confidence)
`VC003`	Virtual camera detected (medium confidence)
`VC004`	Virtual camera software detected
`VC005`	Suspicious camera device labels
`VC006`	Camera device capability mismatch
`VC007`	Suspicious camera device IDs
`VC008`	Camera hardware inconsistencies
`VC009`	No physical media devices
`VC010`	Media device enumeration error

Headless (HD)

Code	Description
`HD001`	Headless browser indicators detected

Integrity Snapshot (IS)

Code	Description
`IS001`	Integrity snapshot tampered
`IS002`	Integrity violations recorded

Cross-Session Inconsistency (CL)

Code	Description
`CL001`	Device type changed between session logs
`CL002`	Browser type changed between session logs
`CL003`	Screen dimensions changed between session logs

High-Risk Example Response

High-Risk Webhook Payload

{
  "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",
  "errors": [
    {
      "code": 1,
      "message": "Image spoof"
    },
    {
      "code": 2,
      "message": "Video spoof"
    }
  ],
  "images": [
    {
      "type": "portrait",
      "data": "base64EncodedImageData..."
    }
  ],
  "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
    }
  },
  "riskEvaluation": {
    "score": 100,
    "level": "CRITICAL",
    "recommendation": "BLOCK",
    "flags": ["VC002", "BR008", "BR009"],
    "signals": {
      "behavioral": null,
      "browser": {
        "score": 100,
        "flags": ["VC002", "BR008", "BR009"]
      }
    }
  }
}