Des webhooks pour les screenings et les alertes

L’API Smart Oversight permet à vos logiciels de créer des clients, de lancer des screenings et de traiter des alertes. Jusqu’ici, c’était à eux d’aller chercher les nouvelles. Ils interrogeaient l’API à intervalles réguliers et comparaient chaque réponse avec ce qu’ils savaient déjà.

Les webhooks inversent le sens de l’échange. Quand un screening se termine, qu’une alerte est traitée ou qu’un client est créé ou modifié, Smart Oversight envoie lui-même une notification à votre serveur.

Le problème de l’interrogation périodique

Un screening prend un moment, le temps de consulter les listes de sanctions, les listes de PPE et les médias négatifs. Si votre système vérifie rarement où il en est, il apprend le résultat en retard. S’il vérifie très souvent, la plupart de ses appels reviennent sans rien de nouveau.

Un parcours d’entrée en relation qui attend ce résultat pour avancer s’accommode mal de l’un comme de l’autre. Avec un webhook, votre système est prévenu à la fin du screening.

Déclarer une adresse de réception

Le point de réception (endpoint) est l’adresse de votre serveur qui recevra les notifications. On le déclare avec POST /v2/webhook_endpoints, en donnant l’adresse dans url et les types d’événements souhaités dans enabled_events. La clé d’API utilisée doit disposer du droit webhooks:write.

La réponse contient le secret de signature du point de réception, et c’est la seule fois qu’il apparaît. Il faut donc l’enregistrer tout de suite. Nous le conservons chiffré et GET /v2/webhook_endpoints ne l’affiche jamais. En cas de perte, on crée un nouveau point de réception, puis on supprime l’ancien avec DELETE /v2/webhook_endpoints/{id}.

L’adresse doit être publique et en HTTPS. Les adresses locales et celles d’un réseau privé sont refusées. Smart Oversight ne suit pas les redirections, si bien qu’une notification n’arrive jamais ailleurs qu’à l’adresse enregistrée.

Les événements

Tous les événements ont la même forme. Chacun porte un id qui commence par evt_, un type, une date created_at et un champ data, qui contient la ressource telle que l’API la renvoie quand on la consulte directement.

• screening.completed : toutes les recherches du screening ont abouti et le résultat est définitif. Le parcours d’entrée en relation peut passer à l’étape suivante.
• screening.failed : au moins une recherche n’a pas abouti et plus aucune ne peut avancer. Le client n’a pas été entièrement contrôlé et quelqu’un doit reprendre le dossier.
• alert.resolved : une décision a été prise sur une alerte, par l’API ou dans l’application Smart Oversight. Votre CRM peut débloquer ou suspendre le dossier sans attendre un e-mail.
• client.created et client.updated : un client a été créé ou modifié par l’API.

Vérifier la signature

Chaque notification porte un en-tête de signature de la forme t=<horodatage unix>,v1=<hex>. La valeur v1 est un HMAC-SHA256 calculé avec le secret du point de réception sur l’horodatage, un point et le corps brut de la requête. Votre serveur s’assure ainsi que la notification vient bien de Smart Oversight et n’a pas été modifiée en route.

Comme l’horodatage est signé avec le corps, une signature interceptée ne vaut pour aucun autre contenu. Il reste à refuser les notifications dont l’horodatage s’écarte trop de votre horloge, ce qui empêche de rejouer un ancien message. L’exemple ci-dessous le fait.

const crypto = require('crypto');

// rawBody : le corps de la requête tel que reçu, avant toute analyse JSON
function verify(rawBody, header, secret) {
  const [, t, v1] = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header) || [];
  if (!t) return false;
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(v1, 'hex'), Buffer.from(expected, 'hex'));
}

Le calcul se fait sur le corps brut. Un JSON analysé puis réencodé ne donnera pas la même signature, même s’il paraît identique.

Pour essayer ce contrôle avant qu’une vraie alerte en dépende, POST /v2/webhook_endpoints/{id}/test envoie un événement de type webhook_endpoint.test à ce seul point de réception. Il a la même forme, la même signature et les mêmes renvois automatiques qu’un événement réel.

Renvois, doublons et ordre d’arrivée

Votre serveur doit répondre vite, avec un statut 2xx. S’il ne répond pas ou renvoie une erreur, Smart Oversight renvoie la notification automatiquement. Le plus sûr est d’accuser réception tout de suite et de faire le traitement ensuite, dans une file ou une tâche de fond.

Une même notification peut arriver deux fois, puisque la livraison se fait « au moins une fois ». L’id de l’événement ne change pas d’un envoi à l’autre et permet d’écarter les doublons.

L’ordre d’arrivée n’est pas garanti non plus. Deux événements sur le même client peuvent arriver dans le désordre. Triez-les par created_at et lisez chaque contenu comme l’état de la ressource à ce moment-là, pas comme une modification à appliquer.

Après une panne

GET /v2/webhook_endpoints/{id}/deliveries liste les envois d’un point de réception, du plus récent au plus ancien. Pour chacun, vous voyez le type d’événement, son statut, le code HTTP renvoyé par votre serveur, la dernière erreur et l’heure de la prochaine tentative. Si le problème venait de chez vous, un certificat expiré ou un déploiement raté par exemple, corrigez-le puis appelez POST /v2/webhook_deliveries/{id}/replay. L’envoi repart aussitôt.

Smart Oversight tient aussi un historique. Chaque événement d’un type écouté par l’un de vos points de réception y est enregistré, que la notification vous soit parvenue ou non. GET /v2/events le renvoie du plus récent au plus ancien et peut le filtrer par type. Après une interruption, votre système le relit jusqu’au dernier événement traité.

L’identifiant evt_ est le même dans la notification et dans l’historique, ce qui évite de traiter deux fois un événement reçu par les deux voies. Pour un rapprochement complet, votre système peut aussi relire vos clients et leurs alertes directement dans l’API.

La page Intégrations présente ce que couvre l’API aujourd’hui. Pour voir comment ces événements s’insèrent dans un parcours complet d’entrée en relation, lisez comment connecter votre screening KYC & LCB/FT à votre CRM.