Événements et envois
Ce que LexOpti envoie à vos points de réception webhook et répond sur GET /v1/events. Pour mettre en place un point de réception, suivez recevoir les webhooks.
Types d’événements
Section intitulée « Types d’événements »| 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 une fois terminée |
alert.created, alert.resolved |
alert_id, client_id, case_id le cas échéant |
decision.pending |
kind, decision_id, client_id, alert_id ou case_id le cas échéant |
classification.validated |
subject (client ou case), avec client_id ou case_id |
case.created |
case_id, client_id (le client principal) |
case.updated |
case_id, client_id (le client principal), changed_fields |
case.risk_level_changed |
case_id |
report.generated |
case_id |
quota.exhausted |
(aucune) |
subscription.inactive |
reason |
access.revoked |
organization_id, reason |
member.enrolled |
enrolment_id, role, status, member_id (mode délégué) |
member.joined |
enrolment_id, member_id, role |
webhook.test |
envoyé seulement par POST /v1/webhook-endpoints/{id}/test |
member.enrolled : un propriétaire ou un administrateur a enrôlé une personne de la structure par votre application (POST /v1/members/enrolments) ; status vaut pending jusqu’à son premier code e-mail, ou activated aussitôt en mode délégué. member.joined : la personne enrôlée est devenue membre (à son premier code, ou aussitôt en mode délégué) ; member_id est son identifiant d’utilisateur, celui de GET /v1/members.
classification.validated est envoyé à chaque validation d’une classification par un membre, dans LexOpti ou les composants embarqués, qui couvre du nouveau hors de l’axe du soupçon (une première validation, d’autres réponses, une nouvelle analyse ou d’autres personnes), même quand le niveau n’a pas changé. Une validation qui ne couvre qu’une modification de l’axe du soupçon n’envoie rien, et le dossier garde son state et son validated_at. Il concerne celle d’un client (subject: client) ou celle d’un dossier (subject: case). La validation d’un dossier envoie un événement, pour le dossier ; les changements de niveau de risque de ses clients envoient toujours client.risk_level_changed. Lisez la classification avec GET /v1/clients/{id}/classification ou GET /v1/cases/{id}/classification. Comme tout événement, il ne porte que des identifiants : aucune réponse, et jamais rien de l’axe du soupçon.
case.created est envoyé quand un dossier est créé : par un membre dans LexOpti ou dans <lexopti-new-case>, par POST /v1/cases, ou par un assistant via le serveur MCP une fois que le membre a confirmé. case.risk_level_changed est envoyé quand un membre valide la classification d’un dossier et que son niveau de risque public (risk_level, le niveau que donne GET /v1/cases/{id}/classification) diffère de celui de la validation précédente, la première validation comprise : une fois par changement, jamais quand une validation garde ce niveau. Le niveau public ne compte jamais l’axe du soupçon : ce qu’un membre soupçonne ne le change pas et n’envoie pas cet événement. Le niveau de risque d’un dossier ne change que de cette façon : de nouvelles analyses font passer sa classification à revalidate, elles ne changent jamais son niveau. Lisez le dossier avec GET /v1/cases/{id}.
client.created est envoyé quand un client est créé, dans LexOpti, un formulaire embarqué ou par POST /v1/clients. client.updated est envoyé quand son identité change (dans LexOpti, un écran embarqué, par PATCH /v1/clients/{id}) ou que sa vigilance continue est activée ou désactivée : changed_fields liste les champs publics modifiés, séparés par des virgules et triés (address.postal_code,person.last_name, monitoring_enabled), jamais leurs valeurs ; une modification qui ne change rien n’envoie rien. client.vigilance_level_changed est envoyé quand le niveau que donnent ses analyses (vigilance_level de GET /v1/clients/{id}) bouge : après une analyse, un contrôle de vigilance ou l’examen d’une correspondance par un membre. Il est calculé quelques secondes après le changement, pas dans sa transaction.
case.updated est envoyé quand l’intitulé, les clients, les parties ou les responsables d’un dossier changent, une fois par partie et par changement : changed_fields dit lesquels (label, clients, parties, assignees). La création du dossier n’envoie que case.created ; ses parties la rejoignent ensuite une à une, chacune envoyant case.updated (changed_fields: parties), qu’elle ait été créée dans LexOpti ou par POST /v1/cases. Les responsables ne figurent pas dans GET /v1/cases/{id} : l’événement dit à vos vues embarquées de se rafraîchir. report.generated est envoyé quand un membre produit une nouvelle version du rapport d’un dossier dont le contenu, l’axe du soupçon mis à part, a changé : lisez-le avec GET /v1/cases/{id}/report. Une nouvelle version qui ne change que l’axe du soupçon n’envoie rien.
client.preliminary_screening_completed est envoyé quand se termine l’analyse préliminaire gratuite d’un client que votre application a créé par l’API ou demandée (POST /v1/clients/{id}/preliminary-screening) (status : completed ou failed, un essai indisponible étant repris sans événement ; outcome : no_match ou possible_match une fois terminée), et quand une nouvelle publication des listes officielles change le résultat d’un client (trigger: list_update) ; un résultat que la nouvelle publication confirme seulement n’envoie rien. Lisez-la avec GET /v1/clients/{id}/preliminary-screening.
decision.pending est envoyé quand une décision attend un membre : une revue de niveau ouverte par la vigilance (kind: level_review, avec client_id, et case_id pour une partie d’un dossier) ou l’examen d’une alerte proposé par un assistant (kind: alert_review_proposal, avec alert_id), une proposition remplacée comprise. Seul un membre décide, dans LexOpti ou ses écrans embarqués : montrez à votre utilisateur où aller.
quota.exhausted est envoyé quand l’organisation dépense son dernier crédit : une analyse qui ouvre ou agrandit un dossier est refusée (quota_exceeded) jusqu’à une offre supérieure ou une recharge, les lancements dans l’année et les places d’un dossier restant gratuits ; lisez GET /v1/usage. subscription.inactive est envoyé une fois quand l’organisation n’est plus cliente (reason, le statut de son abonnement : trial_ended, expired, past_due, canceled, incomplete) : aucune offre ne court, ses crédits sont gelés et les analyses sont refusées (subscription_inactive). Il est envoyé de nouveau pour une période d’inactivité ultérieure, après que l’abonnement a été de nouveau actif. Un essai terminé est remarqué dans les secondes qui suivent sa fin.
access.revoked est le dernier envoi à vos points de réception dans une organisation à laquelle votre application a perdu l’accès (reason : consent_revoked quand il ne reste aucun consentement de membre, blocked par l’organisation, application_disabled par LexOpti). Il est envoyé à chaque point de réception actif de votre application dans cette organisation, quels que soient ses types d’événements, puis le point de réception est désactivé avec disabled_reason: access_revoked ; il ne figure pas dans GET /v1/events, que vos jetons ne lisent plus. Un point de réception déjà désactivé pour une autre raison (failing, member) ne reçoit rien, access.revoked compris, et garde son disabled_reason. Une fois qu’un membre a de nouveau autorisé votre application, réactivez le point de réception par PATCH /v1/webhook-endpoints/{id} avec enabled: true.
Aucun de ces événements ne porte jamais rien de l’axe du soupçon (axe 5 et ses critères de fraude) : sa seule modification n’envoie rien.
{ "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" }}De nouveaux types d’événements peuvent s’ajouter (versions) : ignorez un type que vous ne traitez pas. Le document OpenAPI déclare pour cela la liste x-extensible-enum.
{ type, timestamp, livemode, data }, avec des identifiants seulement dans data : lisez la ressource par l’API pour le reste. À côté de client_id et case_id, data porte vos références du client et du dossier, client_external_ref et case_external_ref, quand vous les avez définies (vos propres identifiants). livemode vaut false pour une organisation bac à sable. Les événements et leurs envois sont conservés 30 jours.
En-têtes et signature
Section intitulée « En-têtes et signature »Les envois suivent Standard Webhooks.
| En-tête | Valeur |
|---|---|
webhook-id |
L’identifiant de l’événement, identique sur les reprises et les rejeux |
webhook-timestamp |
Le moment où la tentative a été signée, en secondes |
webhook-signature |
Les signatures de la tentative, calculées sur le corps brut avec les secrets du point de réception (whsec_…) |
Après POST /v1/webhook-endpoints/{id}/rotate-secret, les secrets précédents signent encore 24 heures : les envois portent entre-temps plusieurs signatures.
Envoi et reprises
Section intitulée « Envoi et reprises »| Règle | Valeur |
|---|---|
| Succès | toute réponse 2xx |
| Délai d’une tentative | 15 secondes |
| Reprises après un échec | 5 s, 5 min, 30 min, 2 h, 5 h, 10 h, 10 h, 14 h, 24 h (environ 2,7 jours) |
| Point de réception en échec pendant tout un cycle | désactivé, disabled_reason: failing |
| Accès de l’application perdu | un dernier access.revoked, puis désactivé, disabled_reason: access_revoked |
Un envoi est pending, succeeded, failed ou cancelled. Il est cancelled, sans jamais compter comme un échec du point de réception, quand l’organisation bloque votre application, quand il ne reste aucun consentement de membre, ou quand LexOpti désactive votre application ; le point de réception reçoit alors access.revoked à la place.
Points de réception
Section intitulée « Points de réception »| Règle | Valeur |
|---|---|
| URL | https:// sur un nom d’hôte public, sans identifiants, pas d’adresse IP, 2 048 caractères au plus |
| Par application et organisation | 10 points de réception au plus, désactivés compris (too_many_webhook_endpoints) |
status |
enabled ou disabled |
disabled_reason |
failing (désactivé par LexOpti après tout un cycle), member (désactivé par PATCH avec enabled: false), access_revoked (votre application a perdu l’accès à l’organisation) |
| Opération | Effet |
|---|---|
POST /v1/webhook-endpoints |
Abonne ; répond le secret une seule fois |
PATCH /v1/webhook-endpoints/{id} |
Change l’URL, les types d’événements ou la description ; enabled: true réactive et efface la série d’échecs |
DELETE /v1/webhook-endpoints/{id} |
Désabonne |
POST …/test |
Envoie un webhook.test signé |
GET …/deliveries |
Liste les tentatives |
POST …/deliveries/{id}/replay |
Renvoie un envoi |
POST …/rotate-secret |
Ajoute un secret, répondu une seule fois |
Le flux d’événements
Section intitulée « Le flux d’événements »GET /v1/events?after=<position> renvoie les événements après cette position (after=0 depuis le plus ancien conservé), dans un ordre sûr vis-à-vis des transactions : un événement apparaît une fois terminées les transactions qui pourraient encore en écrire un antérieur, en général en moins d’une seconde, si bien qu’aucun ne peut apparaître derrière une position déjà lue. Sans after, le flux liste du plus récent au plus ancien, paginé par cursor ; after et cursor ensemble répondent validation_failed. type filtre sur un type d’événement.