Skip to main content
When deepidv sends a webhook event to your endpoint, the request body contains an event object with the event type and the associated data.

​
Event object structure

Every webhook event follows this structure: 
{
  "type": "session.status.verified",
  "data": {
    // Session object — same structure as the Retrieve Session API response
  }
}
FieldTypeDescription
typestringThe event type that triggered the webhook (e.g. session.status.submitted)
dataobjectThe session object associated with the event. This is the same transformed session object returned by the Retrieve Session API

​
Event types

EventTrigger
session.createdA new verification session has been created
session.status.submittedAn applicant has completed and submitted their verification session
session.status.verifiedA verification session has been marked as verified (via manual review or automatic rules)
session.status.rejectedA verification session has been marked as rejected (via manual review or automatic rules)
session.status.failedA verification session has hit the workflow’s configured failed-attempt limit and been auto-failed

​
Headers

Every webhook request includes the following headers:
HeaderDescription
Content-Typeapplication/json
deepidv-signatureYour webhook’s signing secret for verifying the request origin

​
The data object

The data field contains the full session object. This is the same structure returned by the Retrieve Session API endpoint. The key fields are outlined below.

​
Session fields

FieldTypeDescription
idstringUnique session identifier
organization_idstringOrganization that owns this session
user_idstringUser ID of the applicant
sender_user_idstringUser ID of the person who created the session
external_idstringYour external reference ID (if provided at session creation)
statusstringPENDING, SUBMITTED, VERIFIED, REJECTED, VOIDED, EXPIRED, or FAILED
typestringsession, verification, credit-application, silent-screening, or deep-doc
session_progressstringPENDING, STARTED, or COMPLETED
created_atstringISO 8601 timestamp of session creation
updated_atstringISO 8601 timestamp of last update
submitted_atstringISO 8601 timestamp when the applicant submitted
workflow_idstringWorkflow ID used for this session
workflow_stepsstring[]List of workflow step IDs
uploadsobjectBoolean flags for each uploaded document type
meta_dataobjectApplicant submission metadata (IP, device, browser, location)
analysis_dataobjectVerification analysis results

​
analysis_data object

Included when the session has been processed. Contains the full verification analysis:
FieldTypeDescription
created_atstringWhen analysis was performed
id_analysis_dataobjectPrimary ID document analysis (face detection, extracted text, expiry/age/state checks)
secondary_id_analysis_dataobjectSecondary ID document analysis (same structure)
tertiary_id_analysis_dataobjectTertiary ID document analysis (same structure)
id_matches_selfiebooleanWhether the ID photo matches the selfie
faceliveness_scorenumberLiveness confidence score (0–100)
compare_faces_dataobjectFace comparison results with face_match_confidence score
pep_sanctions_dataobjectPEP & sanctions screening results
adverse_media_dataobjectAdverse media screening results
document_risk_dataobjectDocument fraud/risk analysis
custom_form_dataarrayCustom form question/answer entries
For a full breakdown of all nested fields within analysis_data and meta_data, see the Retrieve Session API reference.

​
Example payloads

​
session.created

Sent when a new session is created. At this stage, the session has no analysis data or uploads. 
{
  "type": "session.created",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "organization_id": "org_123",
    "user_id": "usr_456",
    "sender_user_id": "usr_789",
    "external_id": "your-internal-id",
    "status": "PENDING",
    "type": "session",
    "session_progress": "PENDING",
    "workflow_id": "wf_abc123",
    "workflow_steps": ["ID_VERIFICATION", "FACE_LIVENESS"],
    "created_at": "2026-03-23T14:30:00.000Z",
    "updated_at": "2026-03-23T14:30:00.000Z"
  }
}

​
session.status.submitted

Sent when an applicant completes and submits their verification session. The analysis_data field contains the full verification results. 
{
  "type": "session.status.submitted",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "organization_id": "org_123",
    "user_id": "usr_456",
    "sender_user_id": "usr_789",
    "external_id": "your-internal-id",
    "status": "SUBMITTED",
    "type": "session",
    "session_progress": "COMPLETED",
    "workflow_id": "wf_abc123",
    "workflow_steps": ["ID_VERIFICATION", "FACE_LIVENESS"],
    "created_at": "2026-03-23T14:30:00.000Z",
    "updated_at": "2026-03-23T14:35:00.000Z",
    "submitted_at": "2026-03-23T14:35:00.000Z",
    "uploads": {
      "id_front": true,
      "id_back": true,
      "selfie_front": true,
      "selfie_right": true,
      "selfie_left": true,
      "faceliveness": false
    },
    "meta_data": {
      "applicantSubmissionIp": "192.168.1.1",
      "applicantSubmissionDevice": "Mac",
      "applicantSubmissionBrowser": "Chrome",
      "applicantViewTime": "2026-03-23T14:30:05.000Z",
      "applicantSubmissionLocation": "Chicago, United States",
      "applicantSubmissionLocationDetails": {
        "accuracyRadius": 500,
        "continent": "North America",
        "country": "United States",
        "countryIsoCode": "US",
        "latitude": 41.8483,
        "longitude": -87.6517,
        "subdivision": "Illinois",
        "timeZone": "America/Chicago"
      }
    },
    "analysis_data": {
      "created_at": "2026-03-23T14:35:00.000Z",
      "id_matches_selfie": true,
      "faceliveness_score": 95.42,
      "id_analysis_data": {
        "id_extracted_text": [
          { "type": "FIRST_NAME", "value": "JOHN", "confidence": 97.69 },
          { "type": "LAST_NAME", "value": "DOE", "confidence": 85.61 },
          { "type": "DATE_OF_BIRTH", "value": "1995/05/19", "confidence": 96.33 }
        ],
        "expiry_date_pass": true,
        "valid_state_pass": true,
        "age_restriction_pass": true
      },
      "compare_faces_data": {
        "face_match_confidence": 95.69
      },
      "pep_sanctions_data": {
        "peps": null,
        "sanctions": null,
        "both": null
      },
      "adverse_media_data": {
        "total_hits": 0,
        "timestamp": "2026-03-23T14:35:00.000Z"
      }
    }
  }
}

​
session.status.verified

Sent when a session is marked as verified. The payload structure is the same as session.status.submitted, with status updated to VERIFIED. 
{
  "type": "session.status.verified",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "VERIFIED",
    "...": "same structure as session.status.submitted"
  }
}

​
session.status.rejected

Sent when a session is marked as rejected. The payload structure is the same as session.status.submitted, with status updated to REJECTED. 
{
  "type": "session.status.rejected",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "REJECTED",
    "...": "same structure as session.status.submitted"
  }
}

​
session.status.failed

Sent when a session is auto-failed by the system after reaching the workflow’s configured maximum number of failed attempts. The payload structure is the same as session.status.submitted, with status set to FAILED, session_progress set to COMPLETED, and meta_data.failureData populated with the recorded attempts. 
{
  "type": "session.status.failed",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "FAILED",
    "session_progress": "COMPLETED",
    "meta_data": {
      "applicantSubmissionIp": "192.168.1.1",
      "failureData": {
        "failedAttempts": 3,
        "attempts": [
          { "reason": "NO_FACE_DETECTED", "slot": "PRIMARY",   "failedAt": "2026-03-23T14:30:10.000Z" },
          { "reason": "OCR_NAME_MISSING", "slot": "PRIMARY",   "failedAt": "2026-03-23T14:31:42.000Z" },
          { "reason": "DOC_TYPE_NOT_ALLOWED", "slot": "SECONDARY", "failedAt": "2026-03-23T14:33:08.000Z" }
        ]
      }
    },
    "...": "same structure as session.status.submitted"
  }
}
See failureData for the full field reference. reason is intentionally a loose string — new values may be added over time, so consumers should default-handle unknown values.

​
What to do with each event

EventCommon use cases
session.createdLog session creation, update your internal records, send a confirmation to your system
session.status.submittedTrigger your review workflow, notify reviewers, update applicant status in your system
session.status.verifiedGrant access, activate accounts, send confirmation emails, update CRM records
session.status.rejectedNotify applicant, flag for manual review, trigger re-verification flow
session.status.failedNotify applicant, surface a “contact support” path, and log meta_data.failureData.attempts for diagnostics