Event monitoring

Build withCopy prompt

Once a user exists as an entity, stream their activity — payments, transfers, logins, profile changes, anything you want scored — to the monitoring engine. Each event is scored against your monitoring rules, stored as a browsable signal, and — when it scores high enough — raises an alert.

Ingest an event

Build withCopy prompt

POST /api/identity/events — secret (sk_) key, same base URL and auth as the rest of the Identity Hub.

Request

{
  "externalUserId": "user_42",
  "externalEventId": "txn_10001",
  "type": "transaction.transfer",
  "data": {
    "amount": 48000,
    "currency": "USD",
    "country": "NG",
    "counterparty": "acct_998877",
    "direction": "outbound",
    "channel": "transfer",
    "ip": "102.89.x.x"
  }
}

Response

{
  "id": "evt_01j9ghi000",
  "decision": "ALLOW",
  "riskScore": 0,
  "alertId": null
}

Use the decision to gate your own flow — e.g. let ALLOW through, hold REVIEW for manual approval, reject BLOCK.

Scoring rollout. Rule evaluation is being enabled progressively per organization. Until it is active for yours, events are accepted and stored but return decision: "ALLOW" with riskScore: 0. The request and response shapes do not change when scoring turns on — so you can integrate against this contract now and start acting on decisions the moment it's live.

The data payload

Build withCopy prompt

data is a free-form object, but the built-in monitoring rules look for a set of standard fields. Send the ones that apply and the matching rules light up; omit a field and the rules that need it stay dormant.

Anything else you include is preserved and addressable from custom rules via meta_data.* paths.

The event.flagged webhook

Build withCopy prompt

Whenever an event scores to a non-ALLOW decision, a webhook fires so you don't have to poll:

Device & session signals

Build withCopy prompt

POST /api/identity/signals records device/session signals (fingerprints, session context) tied to an entity. This stream is store-only today — it's persisted for future correlation but not yet scored or surfaced in the dashboard.

{ "externalUserId": "user_42", "type": "device.fingerprint", "data": { "deviceId": "d_123" } }

Returns 202 { "id": "sig_01j9jkl111" }.

Where events show up

Build withCopy prompt

• Every scored event appears in Dashboard → Compliance → Signals (requires signals:read).
• Events that raise an alert appear in Dashboard → Compliance → Alerts (requires alerts:read), where your team can group them into a case.

Best practices

Build withCopy prompt

• Send one event per logical action, with a stable externalEventId, so retries don't double-count.
• Register the entity first. An event references an entity by externalUserId; keep your entity records current so rules that read entity.riskTier / entity.nationality have data.
• Include the standard fields you have — the more of amount, currency, direction, counterparty you send, the more rules can contribute.
• Test on sandbox. Use sk_test_ keys and exercise your rule configuration before pointing production traffic at it.

Errors

Build withCopy prompt

Next steps

Build withCopy prompt

• Monitoring rules — tune thresholds and rules that score these events.
• Alerts, cases & SARs — what happens after an event is flagged.