Webhook Configuration Reference

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_id field 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