Events and deliveries
What LexOpti sends to your webhook endpoints and answers on GET /v1/events. To set up an endpoint, follow receive webhooks.
Event types
Section titled “Event types”| 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.
Payload
Section titled “Payload”{ 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.
Headers and signature
Section titled “Headers and signature”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.
Delivery and retries
Section titled “Delivery and retries”| 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.
Endpoints
Section titled “Endpoints”| 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 |
The events feed
Section titled “The events feed”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.