Synchronous vs Asynchronous Evaluations

RiskOS™ evaluations follow one of two execution patterns depending on the workflow configuration: synchronous (immediate response) or asynchronous (paused for user action, results via webhook).

Comparison

Synchronous execution

sequenceDiagram
    participant App as Your Application
    participant RiskOS as RiskOS™

    App->>RiskOS: POST /api/evaluation
    RiskOS->>RiskOS: Input → Enrichments → Rules → Decision
    RiskOS-->>App: 200 OK (decision + enrichment data)

The workflow completes all steps in a single request-response cycle. The API returns the decision, enrichment data, tags, reason codes, and scores.

When workflows are synchronous

A workflow is synchronous when it contains no user-interaction steps. All enrichment calls, conditions, transformations, and decisions execute server-side without requiring input from the end user.

Asynchronous execution

sequenceDiagram
    participant App as Your Application
    participant RiskOS as RiskOS™
    participant User as End User

    App->>RiskOS: POST /api/evaluation
    RiskOS->>RiskOS: Input → Enrichments → ...
    RiskOS->>RiskOS: Reach async step (OTP / DocV / Wait / Hosted Flow)
    RiskOS-->>App: 200 OK (evaluation_paused + eval_id)
    App->>User: Prompt for action
    User->>RiskOS: Complete action (verify OTP, capture document, etc.)
    RiskOS->>RiskOS: Resume → remaining steps → Decision
    RiskOS-->>App: Webhook: evaluation_completed (decision + data)

The workflow pauses when it reaches a step that requires user action. RiskOS™ returns a response with evaluation_paused status and the eval_id. When the user completes the action, the workflow resumes and delivers the final decision via webhook.

Steps that make a workflow asynchronous

Handling paused evaluations

When an evaluation pauses, your application should:

1. Store the eval_id from the initial API response.
2. Direct the user to complete the required action (redirect to Hosted Flow URL, launch DocV SDK, or prompt for OTP).
3. Listen for webhooks: Subscribe to evaluation_completed and evaluation_paused events.
4. Process the final decision from the webhook payload.

Forcing a resume

If you need to skip a paused step (for example, the user abandoned the flow), send a PATCH request:

PATCH /api/evaluation/{eval_id}
{
  "actions": {
    "resume": true
  }
}

The paused step is skipped (produces no output), and the workflow continues from the next step.

Ending a paused evaluation

To terminate a paused evaluation entirely:

PATCH /api/evaluation/{eval_id}
{
  "actions": {
    "end": true
  }
}

Webhook events for async evaluations

Important: Evaluation webhook events are sent only for asynchronous workflows. If your workflows don't contain async steps, you won't receive these events. Subscribe to decision_update and case events for post-decision notifications.

Related concepts

• Evaluations — The execution model that sync/async applies to
• Workflows — Step types that determine sync vs async behavior
• Statuses & Lifecycle — Evaluation states: processing → paused → completed
• Decisions — How decisions are delivered (API response vs webhook)
• Signals & Attributes — Data collected during async user interactions
• Step-up Verification — A common pattern for async evaluations
• Hosted Flows — Async user interaction via Socure-managed UI
• Cases & Manual Review — Post-decision case processing
• Webhooks — Receiving async results
• Resuming Paused Evaluations — API operations for paused evaluations
• Webhook Event Reference — Full event payload documentation