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

Aspect Synchronous Asynchronous
Response Decision returned in the API response evaluation_paused status returned; decision delivered via webhook
Workflow steps No user-interaction steps (OTP, DocV, Wait, Hosted Flow) Contains at least one user-interaction step
Typical use cases Identity verification, fraud screening, risk scoring Document verification, OTP challenges, multi-step onboarding
Webhook required Optional (for case updates, watchlist alerts) Required (for receiving the final decision)
Latency Milliseconds to seconds Seconds to hours (depends on user action)

Synchronous execution

RiskOS™Your ApplicationRiskOS™Your ApplicationPOST /api/evaluationInput → Enrichments → Rules → Decision200 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

End UserRiskOS™Your ApplicationEnd UserRiskOS™Your ApplicationPOST /api/evaluationInput → Enrichments → ...Reach async step (OTP / DocV / Wait / Hosted Flow)200 OK (evaluation_paused + eval_id)Prompt for actionComplete action (verify OTP, capture document, etc.)Resume → remaining steps → DecisionWebhook: 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

Step What it waits for
OTP User enters a one-time passcode sent via SMS, voice, or email
DocV (Predictive Document Verification) User captures a government-issued ID (and optional selfie)
Wait An external API PATCH call resumes the workflow
Hosted Flow User completes a Socure-hosted data collection or verification page

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.

Updating a paused evaluation

To supply additional data to a paused evaluation (for example, after the user provides missing PII), send a PATCH request to /api/evaluation/{eval_id} with the updated fields. The request body follows the same structure as the original POST request. Once the paused step's requirements are met, the workflow resumes automatically.

Setting a decision on a paused evaluation

To end a paused evaluation with a specific decision, send a PUT request to /api/evaluation/{eval_id}/state:

PUT /api/evaluation/{eval_id}/state
{
  "workflow": "your_workflow_name",
  "decision": "REJECT"
}

This sets the evaluation's decision and closes it without resuming the remaining workflow steps.

Webhook events for async evaluations

Event When it fires
evaluation_paused Workflow reaches an async step and pauses
evaluation_completed Workflow resumes, completes, and returns a final decision
workflow_execution_failed Workflow encounters an unrecoverable error during execution

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.