## 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](mailto:support@socure.com) 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:

1. **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.
2. **Use the Evaluation API**: For missed `evaluation_completed` events, retrieve results directly using the `eval_id` via the [Get Evaluation endpoint](https://help.socure.com/riskos/reference/get-evaluation).
3. **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.