Événements webhook KYT pour la surveillance des transactions

Le service Know Your Transaction (KYT) de Youverify émet des webhooks tout au long du cycle de vie de la surveillance des transactions : de la création d’un enregistrement client aux résultats d’évaluation, puis à la création et au triage des alertes. Abonnez-vous à ces événements pour bâtir des workflows de réponse à la fraude en temps réel dans vos propres systèmes.

Types d’événements KYT

Événement	Déclencheur
`tm.client.created`	Un nouveau client KYT (particulier ou entreprise) a été créé
`tm.client.updated`	Un enregistrement client KYT existant a été mis à jour
`tm.evaluation.started`	Une évaluation de transaction a démarré
`tm.evaluation.completed`	Une évaluation de transaction est terminée
`tm.transaction.updated`	Un enregistrement de transaction a été mis à jour
`tm.alert.created`	Une règle de surveillance des transactions s’est déclenchée et a créé une nouvelle alerte
`tm.alert.triage.created`	Un enregistrement de triage a été créé pour une alerte existante
`tm.alert.updated`	Le statut d’une alerte a été mis à jour

Toutes les charges utiles de webhooks KYT incluent un champ eventId (UUID) de premier niveau que vous pouvez utiliser comme clé d’idempotence pour ignorer en toute sécurité les livraisons en double.

Événements d’alerte

`tm.alert.created`

Youverify émet cet événement lorsque le moteur de surveillance des transactions évalue une transaction et qu’un seuil de règle est franchi, ce qui crée une nouvelle alerte. Il s’agit de l’événement principal à suivre pour une réponse à la fraude en temps réel.

Exemple de charge utile

{
  "businessId": "61d880f1e8e15aaf24558f1a",
  "eventId": "26800455-009f-479c-a521-7ade761e7542",
  "event": "tm.alert.created",
  "apiVersion": "v1",
  "data": {
    "id": "659560cdb7cc04aa50134b67",
    "tag": "Fraud",
    "ruleId": "653bc228212e5d79592bab1a",
    "ruleScore": 87,
    "actorId": "653bbf58d90bc8280c533de6",
    "ruleAction": "Reject",
    "riskLevel": "CRITICAL",
    "valueAtRisk": 710296,
    "currencyCode": "NGN",
    "weightedScore": 65.11,
    "transactionIds": ["65955f85d22a9ec93a0c0dde"],
    "status": "UN_ACTIONED",
    "detectionDate": "2024-01-03T13:26:32.724Z",
    "createdAt": "2024-01-03T13:27:41.639Z",
    "businessId": "61d880f1e8e15aaf24558f1a"
  },
  "createdAt": 1709851492
}

Champs de la charge utile d’alerte

string

Identifiant unique de l’enregistrement d’alerte.

string

Gravité de l’alerte. Voir les valeurs de gravité des alertes ci-dessous.

number

Score attribué par la règle déclenchée (0–100).

number

Score de risque pondéré combiné de toutes les règles déclenchées.

string

Action recommandée par la règle : Reject, Warning ou Review.

string

Étiquette de catégorie de risque, par exemple Fraud, AML, Structuring.

array

Identifiants des transactions ayant déclenché cette alerte.

number

Valeur cumulée des transactions (en unités monétaires mineures) considérée comme à risque.

string

Statut actuel de l’alerte. Commence à UN_ACTIONED. Les mises à jour sont transmises via tm.alert.updated.

Événements d’évaluation

`tm.evaluation.completed`

Youverify émet cet événement lorsqu’une évaluation de transaction se termine, soit parce que toutes les règles ont fini d’être traitées, soit parce qu’un franchissement de seuil de règle a été détecté.

Exemple de charge utile

{
  "eventId": "24242cb7-7bb7-4a51-802a-ff5fde13e792",
  "event": "tm.evaluation.completed",
  "apiVersion": "v1",
  "data": {
    "id": "65e51c4097c2b9acd520705f",
    "transactionIds": ["65e51c3f97c2b9acd520705d"],
    "businessId": "61d880f1e8e15aaf24558f1a",
    "triggeredTags": [
      {
        "tag": "Transaction Status",
        "ruleScore": 50,
        "ruleId": "65ca95ca117fae26f1275a71",
        "ruleAction": "Warning"
      }
    ],
    "valueAtRisk": 593000,
    "currency": "NGN",
    "detectionDate": "2024-03-04T01:56:32.072535+01:00",
    "createdAt": "2024-03-04T00:56:32.726Z"
  },
  "createdAt": 1709513793
}

Champs de la charge utile d’évaluation

array

Liste des règles déclenchées pendant cette évaluation, chacune avec tag, ruleScore, ruleId et ruleAction.

number

Valeur totale des transactions considérée comme à risque dans cette évaluation.

string

Code de devise ISO 4217 des transactions évaluées.

Valeurs de gravité des alertes

Le champ data.riskLevel utilise les niveaux de gravité suivants :

Valeur	Description
`LOW`	Anomalie mineure ; à titre informatif uniquement
`MEDIUM`	Schéma notable ; envisagez un examen
`HIGH`	Signal de risque important ; action recommandée
`CRITICAL`	Risque grave ; action immédiate requise

Événements client

Youverify émet les événements tm.client.created et tm.client.updated chaque fois qu’un enregistrement client du service KYT est créé ou modifié. Ces événements vous permettent de maintenir vos propres fiches clients synchronisées avec le service KYT de Youverify.

{
  "event": "tm.client.created",
  "apiVersion": "v1",
  "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "clientId": "client_abc123",
    "businessId": "61d880f1e8e15aaf24558f1a",
    "type": "individual",
    "createdAt": "2024-01-15T10:30:00.000Z"
  },
  "createdAt": 1705315800
}

Comment trier les alertes

Lorsque votre système reçoit un événement tm.alert.created, vous disposez de deux options pour le trier :

Triage via le tableau de bord

Ouvrez l’alerte dans le tableau de bord Cowork sur cowork.youverify.co, examinez les détails de la transaction et enregistrez votre décision (approuver, rejeter, escalader ou classer).

Triage via l'API Cases

Utilisez l’API Cases pour ouvrir par programmation un dossier pour l’alerte, l’assigner à un analyste et enregistrer la décision de triage. Consultez la référence Case Management pour le détail des endpoints.

Utilisez le champ eventId comme clé d’idempotence lorsque vous écrivez les données d’alerte dans votre base de données. Si Youverify réessaie une livraison, vous pouvez ignorer en toute sécurité les doublons en vérifiant si vous avez déjà traité cet eventId.

Démarrage

Concepts de la plateforme

Guides d'implémentation

Webhooks et événements

SDK

Ressources

Événements webhook KYT pour la surveillance des transactions

Types d’événements KYT

Événements d’alerte

`tm.alert.created`

Exemple de charge utile

Champs de la charge utile d’alerte

Événements d’évaluation

`tm.evaluation.completed`

Exemple de charge utile

Champs de la charge utile d’évaluation

Valeurs de gravité des alertes

Événements client

Comment trier les alertes

Triage via le tableau de bord

Triage via l'API Cases

​Types d’événements KYT

​Événements d’alerte

​tm.alert.created

​Exemple de charge utile

​Champs de la charge utile d’alerte

​Événements d’évaluation

​tm.evaluation.completed

​Exemple de charge utile

​Champs de la charge utile d’évaluation

​Valeurs de gravité des alertes

​Événements client

​Comment trier les alertes

Triage via le tableau de bord

Triage via l'API Cases

Types d’événements KYT

Événements d’alerte

`tm.alert.created`

Exemple de charge utile

Champs de la charge utile d’alerte

Événements d’évaluation

`tm.evaluation.completed`

Exemple de charge utile

Champs de la charge utile d’évaluation

Valeurs de gravité des alertes

Événements client

Comment trier les alertes