RiskOS™ uses **webhooks** to deliver asynchronous results — for example, when a paused evaluation completes or a case status changes. RiskOS™ sends an HTTPS `POST` to your configured endpoint whenever a subscribed event occurs.

> 📘
>
> **Setting up webhooks?** This page is the API reference. For configuring endpoints, subscribing to events, and testing delivery in the Dashboard, see the [Webhooks guide](https://help.socure.com/riskos/docs/webhooks).

## The event envelope

Every webhook is delivered as a JSON envelope with the event metadata at the top level and the event-specific payload under `data`:

```json
{
  "event_id": "336ccd2a-b3a8-49a8-b2cc-89a4ae90feeb",
  "event_at": "2026-06-26T16:16:23.104Z",
  "event_type": "evaluation_completed",
  "data": {
    "id": "onb-12345",
    "eval_id": "8770e076-f568-48a9-8201-dca13087e592"
  }
}
```

| Field         | Description                                                        |
|---------------|--------------------------------------------------------------------|
| `event_id`   | Unique identifier for this event delivery                          |
| `event_at`   | Timestamp when the event was generated                             |
| `event_type` | The event that triggered the webhook (see below)                  |
| `data`       | The event-specific payload                                          |

Any [`customer_metadata`](https://help.socure.com/riskos/reference/customer-metadata) you sent on the evaluation is echoed at the top level of the envelope.

## Event types

| Event                        | Sent when                                              |
|------------------------------|------------------------------------------------------|
| `evaluation_completed`       | An asynchronous evaluation finishes and a decision is available |
| `decision_update`           | A reviewer changes the decision on a case           |
| Case management events       | A case is created, updated, or closed                |
| Watchlist monitoring events   | A monitored entity changes on a watchlist           |

For the full list and subscription options, see [Webhook events](https://help.socure.com/riskos/docs/webhook-events).

## Delivery and retries

- Webhooks are delivered over HTTPS `POST` and support Basic, Bearer, and OAuth 2.0 authentication.
- Failed deliveries are retried with backoff.
- Respond with a `2xx` status to acknowledge receipt; non-`2xx` responses are treated as failures and retried.

## Payload reference

- [RiskOS™ Webhook](https://help.socure.com/riskos/reference/riskoswebhook) — the full webhook payload schema

Updated 2 days ago