## 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:

```json
{
  "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](https://help.socure.com/riskos/reference/postevaluation). See the [Webhook event reference](https://help.socure.com/riskos/docs/webhook-events) 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

- **Validate authentication** on every incoming request before processing the payload.
- **Respond quickly** — acknowledge receipt with a `200` status 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`, and `event_at` for observability and replay support.