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 |
RiskOS™ sends a UUID token in the Authorization: Bearer header.
| Field | Description |
|---|---|
| Token | A UUID bearer token |
RiskOS™ performs a client credentials exchange before each delivery to obtain a fresh access token.
| Field | Description |
|---|---|
| Client ID | OAuth 2.0 client identifier |
| Client secret | OAuth 2.0 client secret |
| Token URL | The OAuth 2.0 token endpoint |
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) |
reevaluation | A case was reevaluated and finished processing |
workflow_execution_failed | An evaluation failed to execute |
Case Management events
| Event type | Trigger |
|---|---|
decision_update | A reviewer changed the decision on a case |
fraud_confirming | A case was marked as fraud or non-fraud |
review_case_assigned | A case was assigned to a reviewer |
review_case_unassigned | A case was unassigned from a reviewer |
case_status_updated | A case status or sub-status changed |
case_notes_added | Notes were added to a case |
case_attachment_added | Attachments were added to a case |
Watchlist events
| Event type | Trigger |
|---|---|
watchlist_notification_monitored_search_updated | A monitored entity was added to or removed from a watchlist |
case_management_notification_case_closure | A watchlist case was approved or closed from the RiskOS™ Dashboard |
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) |
For evaluation events, the data object follows the same schema as Evaluation API responses. See the Webhook event reference for event-specific payload details.
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, 3.218.138.162/32, 13.217.134.98/32, 54.85.52.249/32 |
| Production | 35.199.32.202/32, 3.138.161.243, 54.209.34.129/32, 100.24.247.109/32, 44.195.229.53/32 |
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 28 days ago