DocV Webhooks

Configure RiskOS™ webhooks for DocV capture progress events and evaluation completion notifications with decision and reason code payloads.

RiskOS™ can notify your application during and after a Document Verification (DocV) flow. There are two distinct webhook event types you can subscribe to:

DocV Event Webhooks

Webhook event type: case_notes_added
Used to understand where the consumer is in the capture process (opened app, front/back uploaded, consent declined, etc.).
These are lightweight case notes and do not include PII collected during capture.

Evaluation Completion

Webhook event type: evaluation_completed
Used to know when the RiskOS™ evaluation finishes and to read the final DocV results (decision, reason codes, extracted document data, etc.).
This payload can include PII within enrichment request/response objects.

📘
Which one do I need?

Subscribe to both event types if you want progress + final results.

If you only need the final outcome for decisioning, subscribe to Evaluation Completed.

Subscribing to Webhooks

In the RiskOS™ Dashboard, go to Settings → Developers → Webhooks.
Create (or edit) a webhook and subscribe to:
1. case_notes_added event type
2. evaluation_completed event type
Click Continue to Test; if successful, Save to begin receiving real-time notifications.

📘
See also

For more information, see Configure Webhooks in RiskOS™.

1. DocV event webhooks: `case_notes_added`

These events help you track progress in the capture flow.

👍
Tip
Either a DocV webhook or a manual reviewer in RiskOS™ can create case notes. If you only want to process DocV-generated notes, it is recommended to add a filter for:

event_type == "case_notes_added" and

data.reviewer_id == "Webhook"

Event Overview

Event	`data.notes` value	When it fires
Waiting for User to Redirect	`Process Initiated`	The DocV process is initiated, waiting for the user to open the link or scan the QR code
App Opened	`Capture App Opened`	User opens the Capture App
Front Uploaded	`Document Front Uploaded`	User submits an image of the front of the document.
Back Uploaded	`Document Back Uploaded`	User submits an image of the back of the document.
Selfie Uploaded	`Document Selfie Uploaded`	User submits a selfie image
Upload Successful	`Documents Upload Successful`	All required images have been uploaded to Socure.
Session Complete	`Session Complete`	Capture & upload process completes. On the delivery of this webhook, RiskOS™ continues to the next step in the workflow (DocV process is complete)
Consent Declined	`Consent Declined`	Consumer declined the privacy/consent agreement. On the delivery of this webhook, RiskOS™ resumes the workflow with a terminal-negative outcome.
Session Expired	`Session Expired`	The document request link validity has expired. By default, the link expires 24 hours after it is created. On the delivery of this webhook, RiskOS™ resumes the workflow with a terminal-negative outcome. See Customize the Capture App to change this setting.

Example payloads (Case Notes)

Process Initiated

  {
    "id": "9fb17966-c07d-4e33-80d0-6f0a08907c3a",
    "origId": "45ac9531-60ae-4bc7-805e-f7823e4e5545",
    "eventGroup": "DocvNotification",
    "reason": "WAITING_FOR_USER_TO_REDIRECT",
    "environmentName": "Production",
    "event": {
      "created": "2024-08-07T21:13:10.406Z",
      "customerUserId": "111-222-333",
      "docVTransactionToken": "45ac9531-60ae-4bc7-805e-f7823e4e5545",
      "eventType": "WAITING_FOR_USER_TO_REDIRECT",
      "message": "Process Initiated",
      "referenceId": "45ac9531-60ae-4bc7-805e-f7823e4e5545",
      "userId": "444-555-666"
    }
  }

App Opened

{
  "data": {
    "attachments": null,
    "environment_name": "Sandbox",
    "eval_id": "6c81b2ee-4f7e-4ea1-9696-160ecb5b341a",
    "id": "onb-12345",
    "notes": "Capture App Opened",
    "reviewer_id": "Webhook",
    "updated_at": "2025-07-07T21:01:31.29234384Z",
    "workflow": "individual_onboarding"
  },
  "event_at": "2025-07-07T21:01:31.296383102Z",
  "event_id": "6414942b-b3ac-4bec-ad00-da6ea23380d3",
  "event_type": "case_notes_added"
}

Image Upload Events

{
  "data": {
    "attachments": null,
    "environment_name": "Sandbox",
    "eval_id": "6c81b2ee-4f7e-4ea1-9696-160ecb5b341a",
    "id": "onb-12345",
    "notes": "Document Front Uploaded",
    "reviewer_id": "Webhook",
    "updated_at": "2025-07-07T21:07:32.584206875Z",
    "workflow": "individual_onboarding"
  },
  "event_at": "2025-07-07T21:07:32.589211579Z",
  "event_id": "903584c5-8771-4759-b23e-9fc9d9b80b11",
  "event_type": "case_notes_added"
}

Capture Session Outcomes

{
  "data": {
    "attachments": null,
    "environment_name": "Sandbox",
    "eval_id": "6c81b2ee-4f7e-4ea1-9696-160ecb5b341a",
    "id": "onb-12345",
    "notes": "Documents Upload Successful",
    "reviewer_id": "Webhook",
    "updated_at": "2025-07-07T21:08:02.130094221Z",
    "workflow": "individual_onboarding"
  },
  "event_at": "2025-07-07T21:08:02.133677529Z",
  "event_id": "d70203eb-9d14-4a16-ad5b-fc45e6be7ed5",
  "event_type": "case_notes_added"
}

📘
Note:
Treat Consent Declined and Session Expired as terminal-negative, and Session Complete and Documents Upload Successful as terminal-positive.

How `case_notes_added` events interact with workflow execution

Only terminal capture events resume the paused workflow. Intermediate progress events do not affect workflow execution.

Event type	Resumes workflow?	Description
`Session Complete`	Yes	Capture completed. Workflow continues to the next step.
`Session Expired`	Yes	Link expired. Workflow resumes with a terminal-negative outcome.
`Consent Declined`	Yes	Consumer declined consent. Workflow resumes with a terminal-negative outcome.
`Process Initiated`, `Capture App Opened`, `Document Front Uploaded`, `Document Back Uploaded`, `Document Selfie Uploaded`, `Documents Upload Successful`	No	These are progress indicators only. The workflow remains paused.

Automate cancel and resubmit decisions

You can configure your workflow to automatically cancel or resubmit an evaluation based on the DocV outcome — no manual intervention required. Use a Condition step or Decision Rules step after the Document Request enrichment to branch on the capture outcome:

Auto-cancel: Add a condition that checks for a Session Expired or Consent Declined outcome, then route to a Decision step configured with a Cancel outcome.
Auto-resubmit: Add a condition that checks for a resubmit enrichment decision, then route to a Decision step configured with a Resubmit outcome. This prompts the consumer to recapture without requiring a manual review.

📘
Note:
Both Cancel and Resubmit are available as automated decision outcomes in the Decision step and Decision Rules step. You can combine these with any workflow conditions to build fully automated handling for DocV terminal events.

Re-attempt after Session Expired

When a capture session expires, RiskOS™ can generate a new docvTransactionToken within the same evaluation — you do not need to create a new evaluation. Configure your workflow to trigger a re-attempt after receiving the Session Expired event. This preserves the original evaluation context and avoids re-running upstream enrichments.

2. Evaluation Completed

This webhook fires when the RiskOS™ evaluation has finished. Use it to:

Determine the final decision (accept, review, resubmit, reject).
Read DocV results (reason codes, extracted documentData, documentType).
Advance your internal workflow or UI/UX

👍
Correlation tips:

Persist eval_id alongside your internal transaction ID.

From enrichment responses, persist values like referenceId or docvTransactionToken when present.

Example payload (truncated)

{
  "event_type": "evaluation_completed",
  "event_id": "3b31289c-2d4a-4107-80bc-dda63031d5a0",
  "event_at": "2025-07-17T01:20:01Z",
  "data": {
    "eval_id": "11111111-2222-3333-4444-555555555555",
    "id": "client-transaction-12345",
    "workflow": "consumer_onboarding",
    "workflow_id": "5937a624-f298-452c-9169-ceeae9e66b74",
    "workflow_version": "1.0.0",
    "environment_name": "Sandbox",
    "eval_source": "API",
    "eval_start_time": "2025-07-17T01:18:27Z",
    "eval_end_time": "2025-07-17T01:20:01Z",
    "eval_status": "evaluation_completed",
    "decision": "ACCEPT",
    "decision_at": "2025-07-17T01:20:01Z",
    "status": "CLOSED",
    "sub_status": "Accept",
    "tags": [],
    "notes": "",
    "review_queues": [
      "Default Queue"
    ],
    "data_enrichments": [
      {
        "enrichment_name": "Socure Document Request - Default Flow",
        "enrichment_endpoint": "https://service.socure.com/api/5.0/documents/request",
        "enrichment_provider": "SocureDocRequest",
        "status_code": 200,
        "response": {
          "referenceId": "ed6a5077-b272-4a75-8c21-b284e10927cd",
          "status": "SESSION_COMPLETE",
          "data": {
            "docvTransactionToken": "7d6ad42b-f804-4255-b25e-268b8a77c86f",
            "url": "https://verify.socure.com/#/dv/7d6ad42b-f804-4255-b25e-268b8a77c86f"
          }
        }
      },
      {
        "enrichment_name": "Socure Document Verification",
        "enrichment_endpoint": "https://service.socure.com/api/5.0/documents/verify",
        "enrichment_provider": "Socure",
        "status_code": 200,
        "response": {
          "referenceId": "ed6a5077-b272-4a75-8c21-b284e10927c",
          "documentVerification": {
            "decision": {
              "name": "standard",
              "value": "accept"
            },
            "reasonCodes": [
              "I831",
              "I836"
            ],
            "documentType": {
              "type": "Drivers License",
              "country": "USA",
              "state": "NY"
            },
            "documentData": {
              "firstName": "Test",
              "surName": "User",
              "fullName": "Test User",
              "dob": "1990-01-01",
              "documentNumber": "TST1234567",
              "expirationDate": "2030-01-01"
            },
            "digitalIntelligence": {
              "device": {
                "id": "e92ee549-e3c7-4307-9be7-32fefb0db9a4",
                "globalDeviceId": "aecddd42-f223-3333-940c-87baab4c6645",
                "sessionCreatedAt": "2025-07-17T01:18:28Z",
                "deviceCaptureAt": "2025-07-17T01:18:45Z",
                "computed": {
                  "statisticalId": "b90c8faddcd15cd5eafc09bfe4e460d557c5e516f8c5b44b8d3ec1e6f60c30f8",
                  "isVirtualMachine": false, 
                  "sessionAgeMinutes": 45,
                  "deviceNetworkTimezoneOffsetDiffMinutes": 60
                },
                "network": {
                  "connectionIp": "203.0.113.10",
                  "webRtcPublicIp": "203.0.113.10",
                  "webRtcInternalIp": "10.0.0.15",
                  "realIp": "203.0.113.10",
                  "isTor": false,
                  "isProxy": false,
                  "isVpn": false,
                  "isConsumerPrivacy": false,
                  "isRiskyNetwork": false,
                  "isp": "Example ISP",
                  "ispType": "home",
                  "asn": 64500,
                  "asnName": "EXAMPLE-NET",
                  "domainName": "example.net",
                  "org": "Example Org",
                  "isMobileCarrier": false,
                  "speed": "broadband",
                  "networkLocation": {
                    "countryCode": "US",
                    "region": "NY",
                    "city": "New York",
                    "postalCode": "10001",
                    "latitude": 40.75,
                    "longitude": -73.99,
                    "metroCode": 501,
                    "continentCode": "NA",
                    "timezoneName": "America/New_York",
                    "gmtOffset": "-0500"
                  }
                }
              }
            }
          }
        }
      }
    ]
  }
}

📘
PII handling:
The Evaluation Completed payload may include PII inside enrichment request/response. Protect it using your standard security controls (access control, encryption at rest, retention).

Subscribing to Webhooks

1. DocV event webhooks: case_notes_added

Event Overview

Example payloads (Case Notes)

Process Initiated

App Opened

Image Upload Events

Capture Session Outcomes

How case_notes_added events interact with workflow execution

Automate cancel and resubmit decisions

Re-attempt after Session Expired

2. Evaluation Completed

Example payload (truncated)

1. DocV event webhooks: `case_notes_added`

How `case_notes_added` events interact with workflow execution