Webhooks

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
Case notes can be created by either a DocV webhook or a manual reviewer in RiskOS. 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 completed. On the delivery of this webhook, RiskOS will continue to the next step in the workflow (DocV process is complete)
Consent Declined	`Consent Declined`	Consumer declined the privacy/consent agreement.
Session Expired	`Session Expired`	The document request link validity has expired. By default, the link expires 24 hours after it is created. 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.

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
                },
                "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

2. Evaluation Completed

Example payload (truncated)

1. DocV event webhooks: `case_notes_added`