Webhook 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 (for example, `I912`, `R940`) and recent model or logic updates.
No events arriving at all	Complete delivery stoppage may indicate an infrastructure issue on either side — firewall changes, endpoint outage, DNS resolution failure, or a platform-side incident.	1. Verify your endpoint is reachable (test with a `curl` request). 2. Check for recent firewall, WAF, or DNS changes. 3. Confirm IP allowlisting is current for both sandbox and production ranges. 4. Review the webhook delivery log in Developer Workbench → Webhooks for failed delivery attempts. 5. If no delivery attempts appear, contact Socure Support to confirm platform-side delivery status.

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 (for example, evaluation results, case updates, watchlist alerts).

What events can RiskOS™ notify you 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. The system shows success or failure 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.

How do I recover from a webhook delivery gap?

What should I do if my endpoint missed events during an outage?

RiskOS™ does not provide an API to retrieve or replay past webhook events. To recover missed events:

Check the delivery log: In Developer Workbench → Webhooks, review delivery attempts for the affected time. Failed deliveries with retryable status codes (504, 503, 502, 429, 423, 409, 408) will be retried automatically up to 10 times.
Use the Evaluation API: For missed evaluation_completed events, retrieve results directly using the eval_id via the Get Evaluation endpoint.
Reconcile using your records: Compare your expected evaluations (by eval_id) against received webhook events to identify gaps.

How do I prevent data loss from future outages?

Persist every received event_id immediately upon receipt — return a 2xx response before processing.
Implement a reconciliation job that periodically compares expected evaluations against received webhook events.
Set up monitoring and alerting on webhook receipt rates so you detect delivery gaps early.

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?

Sometimes, 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.