Troubleshooting and Best Practices

Troubleshooting

Issue	Explanation	Suggested fix
Tester shows failure	Endpoint may be blocked by a firewall or web application firewall (WAF).	Allowlist RiskOS™ IPs (Sandbox/Prod) and retest.
Duplicate processing	Retries or replayed events can cause duplicate handling.	Use `event_id` for idempotency. Acknowledge quickly and process asynchronously.
Timeouts	The endpoint is performing long or blocking operations inline.	Return a `2xx` response immediately and move heavy processing to background jobs.
`401` / `403` errors	Authentication credentials or tokens are invalid or misconfigured.	Verify Basic credentials, Bearer token, or OAuth2 client details and token URL.
`429` / `5xx` errors	Rate limiting, transient network failures, or downstream service errors.	Ensure the endpoint is retry-safe and idempotent. Add horizontal scaling or caching to handle spikes.
Sudden drop in auto-acceptance rates	May be caused by repeat failed users, demographic shifts, or risk model changes.	Investigate repeat PII patterns. Monitor demographic distribution. Review triggered risk signals (e.g., `I912`, `R940`) and recent model or logic updates.

Webhooks FAQs

General

What are RiskOS™ webhooks and when should I use them?

RiskOS™ webhooks are asynchronous notifications sent to your endpoint when specific events occur (e.g., evaluation results, case updates, watchlist alerts).

What events can RiskOS notify me about?

Evaluation events: evaluation_completed, evaluation_paused, reevaluation, workflow_execution_failed
Case events
Watchlist monitoring and case events
DocV events (progress and final decisions)

Do I need webhooks if I’m already calling the Evaluation API synchronously?

Yes. The synchronous API provides an immediate response, while webhooks deliver asynchronous updates such as final decisions and downstream workflow results.

What events and payload schemas are available?

What event types exist?

Evaluation events: evaluation_completed, evaluation_paused, reevaluation, workflow_execution_failed
Case events
Watchlist monitoring and case events
DocV events (progress vs. final decision)

What fields are included in webhook payloads?

event_id
event_type
workflow
eval_id
created_at
Additional nested data depending on the event type

Which events should I subscribe to for DocV?

case_notes_added → Progress updates
evaluation_completed → Final decision

How do webhooks relate to workflows and solutions?

Which webhooks should I use for different solutions?

Consumer Onboarding
Login & Authentication
Business Onboarding
Hosted Flows

Typically:

evaluation_completed (core event)
Optional: case events or DocV events depending on your workflow

Where can I find webhook docs in context?

Build with RiskOS → Webhooks / Event Subscription Types
Solution documentation pages linking to webhook configuration

Setup & Configuration

How do I configure webhooks in the RiskOS™ Dashboard?

Where do I create or edit a webhook?

Developer Workbench → Webhooks

What fields are required?

Name
URL
Use Case
Event Type(s)
Authentication Type

How do I test a webhook before going live?

Use the Continue to Test button to send a sample payload. Success or failure is shown inline.

How does webhook authentication and security work?

What authentication methods are supported?

Basic Authentication
Bearer Token
OAuth2 (client ID/secret + token URL)

Do I have to use HTTPS?

Yes. Your endpoint must support HTTPS and accept JSON POST requests.

How do I restrict incoming webhook traffic?

Use IP allowlisting for RiskOS™ outbound IP ranges (sandbox and production).

Can I use additional security controls?

mTLS (optional)
Web Application Firewalls (WAFs)
Payload encryption

⚠️ Avoid exposing sensitive data to third-party webhook testing tools.

Delivery, retries, and debugging

How does webhook retry and error handling work?

What happens if my endpoint is down or slow?

RiskOS™ retries failed deliveries using exponential backoff.
Retry attempts: up to 10 times
From the 6th attempt onward, retries occur at ~1-minute intervals

Which status codes trigger retries?

504, 503, 502, 429, 423, 409, 408

How do I make webhook processing idempotent?

Use the event_id to detect and ignore duplicates and design your system to safely handle replays.

How do I debug failing webhooks?

Why is the Dashboard test failing?

Often due to WAF or firewall blocking RiskOS™ IPs.
Solution: allowlist sandbox/prod IP ranges and retry.

Can I re-run a webhook test without enabling it?

Yes. You can manually trigger tests from Developer Workbench → Webhooks.

Specialized and implementation topics

How do watchlist-specific webhooks work?

What watchlist events are available?

Monitoring events (entity matched, updated, removed)
Case Management events (case approved, closed)

Do I need a special endpoint or certificate?

In some cases, you must upload your server’s TLS certificate when registering the endpoint.

Do you have sample code and implementation best practices?

Do you have example code for receiving webhooks?

Yes. Node.js (Express) and Python (Flask) examples are available.
They demonstrate validation, idempotency, and async processing patterns.

Can I process webhooks asynchronously?

Yes (recommended).
Return a 2xx response quickly, then process events in background workers.