Skip to content

Events and deliveries

What LexOpti sends to your webhook endpoints and answers on GET /v1/events. To set up an endpoint, follow receive webhooks.

Type data
check.completed, check.failed check_id, client_id
client.created client_id
client.updated client_id, changed_fields
client.vigilance_level_changed client_id
client.risk_level_changed client_id
client.preliminary_screening_completed client_id, status, trigger, outcome when completed
alert.created, alert.resolved alert_id, client_id, case_id if any
decision.pending kind, decision_id, client_id, alert_id or case_id if any
classification.validated subject (client or case), with client_id or case_id
case.created case_id, client_id (the main client)
case.updated case_id, client_id (the main client), changed_fields
case.risk_level_changed case_id
report.generated case_id
quota.exhausted (none)
subscription.inactive reason
access.revoked organization_id, reason
member.enrolled enrolment_id, role, status, member_id (delegated mode)
member.joined enrolment_id, member_id, role
webhook.test sent only by POST /v1/webhook-endpoints/{id}/test

member.enrolled: an owner or admin enrolled a person of the organization through your application (POST /v1/members/enrolments); status is pending until their first e-mail code, or activated at once in delegated mode. member.joined: the enrolled person became a member (at their first code, or at once in delegated mode); member_id is their user id, the one of GET /v1/members.

classification.validated is sent at each validation of a classification by a member, in LexOpti or the embedded components, that covers something new outside the suspicion axis (a first validation, other answers, a new analysis or other persons), even when the level did not change. A validation that only covers a change to the suspicion axis sends nothing, and the case keeps its state and its validated_at. It concerns a client’s own (subject: client) or a case’s (subject: case). A case’s validation sends one event, for the case; its clients’ risk level changes still send client.risk_level_changed. Read the classification with GET /v1/clients/{id}/classification or GET /v1/cases/{id}/classification. Like every event, it carries ids only: no answer, and never anything of the suspicion axis.

case.created is sent when a case is created: by a member in LexOpti or in <lexopti-new-case>, by POST /v1/cases, or by an assistant through the MCP server once the member confirmed. case.risk_level_changed is sent when a member validates a case’s classification and its public risk level (risk_level, the level GET /v1/cases/{id}/classification gives) differs from the previous validation’s, the first validation included: once per change, never when a validation keeps that level. The public level never counts the suspicion axis: what a member suspects neither changes it nor sends this event. A case’s risk level changes only that way: new analyses mark its classification revalidate, they never change its level. Read the case with GET /v1/cases/{id}.

client.created is sent when a client is created, in LexOpti, an embedded form or POST /v1/clients. client.updated is sent when its identity changes (in LexOpti, an embedded screen, PATCH /v1/clients/{id}) or its ongoing vigilance is switched on or off: changed_fields lists the public fields that changed, comma separated and sorted (address.postal_code,person.last_name, monitoring_enabled), never their values; an edit that changes nothing sends nothing. client.vigilance_level_changed is sent when the level its screening gives (vigilance_level of GET /v1/clients/{id}) moves: after a check, a monitoring run, or a member’s review of a match. It is computed a few seconds after the change, not in its transaction.

case.updated is sent when a case’s label, clients, parties or assignees change, once per part and change: changed_fields names which (label, clients, parties, assignees). The case’s creation sends case.created only; its parties then join one by one, each sending case.updated (changed_fields: parties), whether it was created in LexOpti or by POST /v1/cases. Assignees are not part of GET /v1/cases/{id}: the event tells your embedded views to refresh. report.generated is sent when a member produces a new version of a case’s report whose content, the suspicion axis left out, changed: read it with GET /v1/cases/{id}/report. A new version that only changes the suspicion axis sends nothing.

client.preliminary_screening_completed is sent when a free preliminary screening of a client your application created through the API or asked for (POST /v1/clients/{id}/preliminary-screening) settles (status: completed or failed, an unavailable round being retried without an event; outcome: no_match or possible_match when completed), and when a new publication of the official lists changes a client’s result (trigger: list_update); a result the new publication only confirms sends nothing. Read it with GET /v1/clients/{id}/preliminary-screening.

decision.pending is sent when something awaits a member’s decision: a level review the monitoring opened (kind: level_review, with client_id and case_id for a party of a case) or an assistant’s proposed review of an alert (kind: alert_review_proposal, with alert_id), a replaced proposal included. Only a member decides, in LexOpti or its embedded screens: show your user where to go.

quota.exhausted is sent when the organization spends its last credit: a check that opens or grows a dossier is refused (quota_exceeded) until it moves up an offer or buys a recharge, while launches within a dossier’s year and places stay free; read GET /v1/usage. subscription.inactive is sent once when the organization stops being a client (reason, its subscription’s status: trial_ended, expired, past_due, canceled, incomplete): no offer runs, its credits are frozen and checks are refused (subscription_inactive). It is sent again for a later inactive spell, after the subscription was active again. An ended trial is noticed within seconds of its end.

access.revoked is the last delivery to your endpoints in an organization whose access your application lost (reason: consent_revoked when no member’s consent is left, blocked by the organization, application_disabled by LexOpti). It is sent to every enabled endpoint of your application in that organization, whatever its event types, then the endpoint is disabled with disabled_reason: access_revoked; it is not part of GET /v1/events, which your tokens no longer read. An endpoint already disabled for another reason (failing, member) receives nothing, access.revoked included, and keeps its disabled_reason. Once a member authorizes your application again, enable the endpoint with PATCH /v1/webhook-endpoints/{id} and enabled: true.

None of these events ever carries anything of the suspicion axis (axis 5 and its fraud criteria): a change to it alone sends nothing.

{
"type": "client.updated",
"timestamp": "2026-11-10T09:12:44.512Z",
"livemode": true,
"data": {
"client_id": "6f1b8d6e-2c4a-4f5e-9b1d-3a7c2e8f4d10",
"changed_fields": "address.postal_code,person.last_name",
"client_external_ref": "crm:contact:1042"
}
}
{
"type": "access.revoked",
"timestamp": "2026-11-10T09:30:02.118Z",
"livemode": true,
"data": {
"organization_id": "org_7d2c1b9e",
"reason": "consent_revoked"
}
}

New event types may be added (versioning): ignore a type you do not handle. The OpenAPI document declares the list x-extensible-enum for that reason.

{ type, timestamp, livemode, data }, with ids only in data: read the resource through the API for the rest. Next to client_id and case_id, data carries your references of the client and the case, client_external_ref and case_external_ref, when you set them (your own ids). livemode is false for a sandbox organization. Events and their deliveries are kept 30 days.

Deliveries follow Standard Webhooks.

Header Value
webhook-id The event id, the same on retries and replays
webhook-timestamp When the attempt was signed, in seconds
webhook-signature The signatures of the attempt, computed on the raw body with the endpoint’s secrets (whsec_…)

After POST /v1/webhook-endpoints/{id}/rotate-secret, the previous secrets keep signing for 24 hours: deliveries carry several signatures meanwhile.

Rule Value
Success any 2xx answer
Timeout of an attempt 15 seconds
Retries after a failure 5 s, 5 min, 30 min, 2 h, 5 h, 10 h, 10 h, 14 h, 24 h (about 2.7 days)
Endpoint failing for a whole schedule disabled, disabled_reason: failing
Application’s access lost a last access.revoked, then disabled, disabled_reason: access_revoked

A delivery is pending, succeeded, failed or cancelled. It is cancelled, never counted as a failure of the endpoint, when the organization blocks your application, when no member’s consent is left, or when LexOpti disables your application; the endpoint then receives access.revoked instead.

Rule Value
URL https:// on a public hostname, without credentials, no IP address, 2,048 characters at most
Per application and organization 10 endpoints at most, disabled ones included (too_many_webhook_endpoints)
status enabled or disabled
disabled_reason failing (disabled by LexOpti after a whole schedule), member (disabled with PATCH and enabled: false), access_revoked (your application lost its access to the organization)
Operation Effect
POST /v1/webhook-endpoints Subscribes; answers the secret once
PATCH /v1/webhook-endpoints/{id} Changes the URL, event types or description; enabled: true enables again and clears the failure streak
DELETE /v1/webhook-endpoints/{id} Unsubscribes
POST …/test Sends a signed webhook.test
GET …/deliveries Lists the attempts
POST …/deliveries/{id}/replay Sends a delivery again
POST …/rotate-secret Adds a secret, answered once

GET /v1/events?after=<position> returns the events after that position (after=0 from the oldest kept), in commit-safe order: an event shows once every transaction that may still write an earlier one has ended, usually within a second, so none can appear behind a position already read. Without after, the feed lists the newest first, paged with cursor; after and cursor together answer validation_failed. type filters on one event type.