Aller au contenu

É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.

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.

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.

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.

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

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.