Ongoing monitoring — exactly how it works.
Enrol a subject once and we re-screen it over time against the current watchlists.
When the outcome changes — a new hit, or a stronger match — the case reopens and a
monitoring.alert webhook fires. Nothing here is a black box: the triggers, the
retry behaviour, and the knobs are all spelled out below.
What it does
For each monitored subject we keep a baseline — the decision (Pass / Review / Fail)
and matched entities from the last screen. On every re-screen we compare the fresh result to that
baseline. If the decision is unchanged, nothing happens (no noise). If it escalated
(e.g. Pass → Fail, or a new sanctioned match appeared), we reopen the case as a new
screening and emit a monitoring.alert. You are alerted only when the outcome moves.
Two triggers
| Trigger | When it runs | Which subjects |
|---|---|---|
| Change-driven sweep | Immediately after a watchlist is refreshed/ingested (UN, OFAC, EU, UK, PEP). | Only subjects whose result could be affected by that changed list — targeted, not everyone. |
| Scheduled re-screen | A background service wakes on a poll interval and runs two cadences: a daily delta (subjects not re-screened recently) and a monthly full (every monitored subject). | Time-based safety net, independent of list changes — catches drift even when no list updated. |
Retries & failure handling
This is the part people ask about, so plainly:
- A single subject's re-screen failure never stops the sweep. It's logged and skipped; every other subject in the run still gets processed.
- No tight retry loop. We don't hammer a failed subject within the same run. Instead it is naturally re-attempted on the next cadence — the next change-driven sweep for its lists, or the next daily/monthly scheduled run. So a transient failure self-heals on the following pass, without back-pressure or runaway retries.
- Cancellation is respected — a shutdown mid-sweep stops cleanly and resumes next cycle.
- Webhook delivery has its own separate retries. Emitting the alert and delivering it are different steps: the re-screen decides an alert is due; the webhook dispatcher then delivers it best-effort with retries, and every attempt (success or failure, with the HTTP status) is recorded in your Delivery history. See Webhooks.
Cadence & configuration
Monitoring is opt-in. The engine-level cadence knobs (defaults shown) are:
| Setting | Default | Meaning |
|---|---|---|
Monitoring:Enabled | false | Master switch for the sweep + alerts. |
Monitoring:ScheduledRescreen:Enabled | false | Master switch for the time-based re-screen host. |
…:PollIntervalMinutes | 60 | How often the host wakes to check whether a cadence is due. |
…:DailyIntervalHours | 24 | The daily-delta window: re-screen subjects not screened within this many hours. |
…:FullIntervalDays | 30 | The monthly-full cadence: re-screen every monitored subject this often. |
Per tenant, an admin can turn monitoring on/off and set a cadence override
(days) from the /console tenant settings — or a tenant can manage its own from the
Settings panel in the cases console. A disabled tenant is skipped entirely by the sweep.
Enrolling, viewing & stopping
Enrol a subject at screen time — set monitor: true on
POST /v1/screenings/check, or tick “Enrol in ongoing monitoring” under the name box
in the cases console. Enrolment upserts by a stable per-tenant subject key, so re-enrolling the same
subject updates rather than duplicates.
# Screen and enrol for ongoing monitoring
POST /v1/screenings/check
{ "fullName": "Vladimir Putin", "monitor": true }
| Action | API | In the console |
|---|---|---|
| List monitored subjects | GET /v1/monitoring/subjects | Settings → Monitored subjects |
| Stop monitoring one | DELETE /v1/monitoring/subjects/{id} | Settings → Stop |
| Read / set monitoring config | GET / PUT /v1/monitoring/config | Settings → Ongoing monitoring |
What you get on a change
When a re-screen escalates, the subject's case reopens (a fresh screening lands in your queue) and a
monitoring.alert webhook is delivered with the updated, PII-light result. Verify its
HMAC-SHA256 signature exactly as for any event — see Webhooks. If you have
no webhook registered, the reopened case is still visible in the console; the webhook is just the push
channel.
Everything above is measured against production behaviour and is reproducible via the API and the playground. No hidden re-screen storms, no silent drops — failures self-heal on the next cadence and every webhook attempt is logged.