Webhook Configuration Reference
Reference for RiskOS™ webhook settings, including authentication schemes, event subscriptions, delivery options, and retry behavior.
Webhook configuration fields
When you create or edit a webhook in the RiskOS™ Dashboard (Developer Workbench > Webhooks), you configure the following fields:
| Field | Type | Required | Description |
|---|---|---|---|
| Name | String | Yes | A descriptive label to identify the webhook |
| URL | String | Yes | The HTTPS endpoint that receives webhook events |
| Use case | String | Yes | The RiskOS™ use case this webhook subscribes to |
| Event types | Array | Yes | One or more event types that trigger this webhook |
| Auth type | String | Yes | Authentication method for outbound requests |
| Status | String | — | ACTIVE or INACTIVE |
Authentication schemes
Each webhook is configured with one of three authentication methods. RiskOS™ includes the configured credentials in every outbound webhook request.
RiskOS™ sends the username and password as a Base64-encoded Authorization: Basic header.
| Field | Description |
|---|---|
| Username | The Basic Auth username |
| Password | The Basic Auth password |
Event types
Webhooks subscribe to specific event types. When a subscribed event occurs, RiskOS™ sends an HTTP POST request to your configured endpoint.
Evaluation events
| Event type | Trigger |
|---|---|
evaluation_completed | An evaluation has finished processing with a final decision |
evaluation_paused | An evaluation paused waiting for async input (for example, DocV, OTP) |
evaluation_resumed | A paused evaluation has been resumed with new data |
Case Management events
| Event type | Trigger |
|---|---|
case_decision_changed | A reviewer changed the decision on a case |
case_status_changed | The status of a case changed (for example, OPEN → CLOSED) |
case_assigned | A case was assigned to a reviewer |
Watchlist events
| Event type | Trigger |
|---|---|
watchlist_match_found | The system identified a new watchlist match during screening |
watchlist_monitoring_alert | Ongoing monitoring detected a change in watchlist status |
Note: Available event types depend on your account entitlements. Not all event types may be visible in the dashboard.
Webhook payload structure
Every webhook delivery uses this standard envelope:
{
"event_id": "336ccd2a-b3a8-49a8-b2cc-89a4ae90feeb",
"event_at": "2025-01-15T13:04:11.468Z",
"event_type": "evaluation_completed",
"data": {
"id": "onb-12345",
"eval_id": "6dc8f39c-ecc3-4fe0-9283-fc8e5f99e816",
"workflow": "consumer_onboarding",
"decision": "ACCEPT",
"status": "CLOSED",
"data_enrichments": [ ... ]
}
}| Field | Type | Description |
|---|---|---|
event_id | String (UUID) | Unique identifier for this webhook delivery; use for idempotency |
event_at | String (ISO 8601) | Timestamp when the event occurred |
event_type | String | The event type that triggered this delivery |
data | Object | Event-specific payload (varies by event type) |
Retry behavior
If webhook delivery fails, RiskOS™ retries with exponential backoff:
| Setting | Value |
|---|---|
| Maximum attempts | 10 |
| Initial backoff | Starts small and increases exponentially |
| Maximum backoff | 60 seconds |
| Attempts 6–10 | Fixed 1-minute intervals |
| Retried status codes | 504, 503, 502, 429, 423, 409, 408 |
Important: Design your webhook receiver for idempotency. Use the
event_idfield to detect and discard duplicate deliveries. RiskOS™ may retry successfully delivered events in rare edge cases.
IP allowlisting
If your infrastructure requires IP allowlisting, permit outbound connections from the following RiskOS™ IP addresses:
| Environment | IP addresses |
|---|---|
| Sandbox | 35.230.191.253/32 |
| Production | 35.199.32.202/32, 3.138.161.243 |
Tip: If you use a WAF or API gateway, add these IPs to your source allowlist and confirm with an end-to-end test.
Delivery requirements
Your webhook endpoint must meet these requirements for reliable delivery:
| Requirement | Details |
|---|---|
| Protocol | HTTPS only (TLS 1.2 or higher) |
| Method | Accept POST requests |
| Content type | Accept application/json payloads |
| Response | Return a 2xx status code to acknowledge receipt |
| Response time | Respond within 30 seconds to avoid timeout |
| Authentication | Validate the authentication credentials sent by RiskOS™ |
Header variables
RiskOS™ supports custom static header variables that are included in every webhook delivery. To configure custom headers, contact your Solutions Consultant.
Security recommendations
- Validate authentication on every incoming request before processing the payload.
- Respond quickly — acknowledge receipt with a
200status and process the payload asynchronously. - Treat payloads as untrusted — enforce JSON schema validation and size limits.
- Store minimal data from the webhook; fetch additional details from RiskOS™ APIs if needed.
- Log delivery metadata — record
event_id,event_type, andevent_atfor observability and replay support.
Related
Updated about 4 hours ago