Guide des webhooks

Utilisez des webhooks pour recevoir les événements KYC, AML et de vérification d’identité de votre intégration ComplyCube.

Vue d’ensemble

ComplyCube utilise les webhooks pour notifier votre application lorsqu'un événement se produit dans votre compte. Les webhooks sont particulièrement utiles pour les événements asynchrones, comme lorsqu'une vérification est terminée.

Toutes les intégrations ComplyCube ne nécessitent pas de webhooks. Continuez à lire pour en savoir plus sur les webhooks et savoir quand vous devriez les utiliser.

Introduction aux webhooks

Les webhooks combinent plusieurs éléments pour créer un système de notification et de réaction au sein d'une intégration.

Métaphoriquement, les webhooks sont comme un numéro de téléphone que ComplyCube appelle pour vous notifier l'activité de votre compte. Il pourrait s'agir d'une vérification de document terminée. Le point de terminaison du webhook est la personne qui répond à cet appel et qui prend des mesures en fonction des informations spécifiques qu'il reçoit.

Concrètement, le point de terminaison du webhook n'est qu'un peu plus de code sur votre serveur. Le point de terminaison du webhook a une URL associée (par exemple, https://example.com/webhooks). Les notifications ComplyCube sont Événement objets. Cet objet contient toutes les informations pertinentes sur ce qui vient de se passer, y compris le type d'événement et les données associées à cet événement. Le point de terminaison du webhook utilise les détails de l'événement pour prendre les mesures requises, comme mettre temporairement en attente le compte ou la transaction d'un client.

Composants du webhook

L'intégration des webhooks ComplyCube comprend les éléments suivants :

Événements. Une action ou une modification des données qui génère des notifications. Les webhooks peuvent être utilisés pour créer des alertes qui déclenchent ces événements. Veuillez consulter la page de l'API Webhooks pour la liste des types d'événements pris en charge.
Abonnements. Configurés dans le portail développeur ou via l'API pour s'abonner aux notifications associées à un type d'événement spécifique.
URL de notification. Le service configurable dans l'application auquel les alertes sont envoyées.
Corps de la notification. Détails sur l'objet associé à l'événement.

Quand utiliser

De nombreux événements qui se produisent au sein du compte ComplyCube ont des résultats synchrones — immédiats et directs — à une requête exécutée. Par exemple, une requête réussie vers créer un client renvoie immédiatement un client objet. De telles requêtes ne nécessitent pas de webhooks, car les informations clés sont déjà disponibles.

D'un autre côté, Les vérifications sont asynchrones : elles se produisent plus tard et pas directement en réponse à l'exécution de votre code. Avec ces événements, ComplyCube doit notifier votre intégration des modifications de statut d'un objet afin que votre intégration puisse effectuer les étapes suivantes.

Les actions spécifiques de votre point de terminaison webhook varient selon l'événement. Quelques exemples :

En fonction du résultat d'une vérification, décidez d'accepter ou de rejeter la demande d'un client pour être intégré à votre plateforme.
Effectuez des actions de suivi après avoir été alerté par notre moteur de surveillance continue en temps réel qu'un statut de client a changé.

Vérification de la signature

Utilisation des SDK officiels

ComplyCube signe les événements webhook qu'il envoie à vos points de terminaison en incluant une signature dans l'en-tête ComplyCube-Signature . Cela vous permet de vérifier que les événements ont été envoyés par ComplyCube, et non par un tiers. Vous pouvez vérifier les signatures à l'aide de nos bibliothèques officielles ou manuellement avec votre propre solution.

Utilisez l'une de nos bibliothèques officielles pour vérifier les signatures. Vous effectuez la vérification en fournissant la charge utile de l'événement, l' ComplyCube-Signature en-tête, et le secret du point de terminaison. Si la vérification échoue, ComplyCube renvoie une erreur.

const { EventVerifier } = require('@complycube/api')

// Fournissez votre secret de webhook à EventVerifier 
const webhookSecret = process.env.COMPLYCUBE_WEBHOOK_SECRET;
const eventVerifier = new EventVerifier(webhookSecret);

// Cet exemple utilise Express pour recevoir les webhooks
const app = require('express')();

// Utilisez body-parser pour récupérer le corps brut sous forme de tampon
const bodyParser = require('body-parser');

// Faire correspondre le corps brut au type de contenu application/json
app.post('/webhook', bodyParser.json(), (request, response) => {
  const signature = request.headers['complycube-signature'];

  let event;

  try {
    event = eventVerifier.constructEvent(
      JSON.stringify(request.body),
      signature
    );
  }
  catch (err) {
    response.status(400).send(`Erreur de webhook : ${err.message}`);
  }

  // Traitez l'événement
  switch (event.type) {
    case 'check.completed': {
      const checkId = event.payload.id;
      const checkOutcome = event.payload.outcome;
      console.log(`La vérification ${checkId} est terminée avec le résultat ${checkOutcome}`);
      break;
    }
    case 'check.pending': {
      const checkId = event.payload.id;
      console.log(`La vérification ${checkId} est en attente`);
      break;
    }
    // ... gérer les autres types d'événements
    default: {
      // Type d'événement inattendu
      return response.status(400).end();
    }
  }

  // Renvoyez une réponse pour accuser réception de l'événement
  response.json({received: true});
});

app.listen(4242, () => console.log('En cours d'exécution sur le port 4242'));

import json
import os
import flask
from flask import request, jsonify
import complycube.eventverifier as ccevnt

# Exemple d'application Flask
app = flask.Flask(__name__)

# Fournissez votre secret de webhook à EventVerifier
ev = ccevnt.EventVerifier(os.getenv('COMPLYCUBE_WEBHOOK_SECRET'))

@app.route('/webhook', methods=['POST'])
def webhook():
    if 'complycube-signature' not in request.headers:
        return jsonify({'received':'False'}), 400
    
    signature = request.headers['complycube-signature']
    try:
        event = ev.construct_event(request.get_data(),signature)
        check_id = event.payload.id
        if event.type == 'check.completed':
            check_outcome = event.payload.outcome
            print('La vérification %s est terminée avec le résultat %s' % 
                  (check_id, check_outcome))
        elif event.type == 'check.pending':
            print('La vérification %s est en attente' % check_id)
        # ... Traitez les autres événements attendus
        else:
            return jsonify({'received':'False'}), 400      
    except VerificationError:
        return jsonify({'received':'False'}), 400 
    
    return jsonify({'received':'True'}), 200

app.run()

use ComplyCube\ComplyCubeClient;
use ComplyCube\Model\Event;
use ComplyCube\EventVerifier;
use ComplyCube\Exception\VerificationException;

header("Access-Control-Allow-Origin: *");
header("Content-Type: application/json; charset=UTF-8");
header("Access-Control-Allow-Methods: POST");
header("Access-Control-Max-Age: 3600");
header("Access-Control-Allow-Headers: Content-Type, Authorization, Complycube-Signature, X-Requested-With");
define("SIGNATURE_KEY", 'complycube-signature');

$data = file_get_contents('php://input');
$verifier = new \ComplyCube\EventVerifier('WEBHOOK_SECRET');
$headers = apache_request_headers();

try {
    if (!isset($headers[SIGNATURE_KEY])) {
        http_response_code(400);
        return;
    }
    $event = $verifier->constructEvent($data, $headers[SIGNATURE_KEY]);
    switch ($event->type) {
        case "check.completed":
            $outcome = $event->payload->outcome;
            # traiter la vérification terminée
            break;
        case "check.pending":
            # traiter la vérification en attente
            break;
        default:
            http_response_code(400);
            return;
    }
    http_response_code(200);
    return;
} catch (\ComplyCube\Exception\VerificationException $e) {
    http_response_code(400);
    return;
}

using System.Text;
using System.Text.Json;
using ComplyCube.Net;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Primitives;

namespace CCSimpleDotNetSample.Controllers {
 [ApiController]
 [Route("[controller]")]
 public class SimpleEventListenerController: ControllerBase {
  [HttpPost]
  public async Task < IActionResult > Post() {
   var re = Request;
   StringValues payloadSignature;
   re.Headers.TryGetValue("complycube-signature", out payloadSignature);

   // Remplacez WEBHOOK_SECRET par le secret de votre console de développement
   var evr = new EventVerifier("WEBHOOK_SECRET");

   // Utilisez StreamReader pour lire tout le corps de l'événement
   using(var reader = new StreamReader(Request.Body, Encoding.UTF8)) {
    var payloadText = await reader.ReadToEndAsync();
    
    if (string.IsNullOrWhiteSpace(payloadText)){
     return StatusCode(400);
    }
    
    try {
     // Construisez l'objet Event et confirmez sa signature
     var receivedEvent = evr.ConstructEvent(payloadText, payloadSignature);
     if (receivedEvent != null) {
      var payloadObject = JsonSerializer.Deserialize<Dictionary<string, object>>(
       payloadText
      );
      
      // Traitez la charge utile et agissez en conséquence
      if (payloadObject.TryGetValue("type", out var eventTypeObj) &&
       payloadObject.TryGetValue("payload", out var eventPayloadObj)) {
       var eventType = eventTypeObj.ToString();
       var eventPayload = JsonSerializer.Serialize(eventPayloadObj);

       switch (eventType) {
        case "check.completed":
         if (eventPayloadObj is Dictionary < string, object > payloadDict &&
          payloadDict.TryGetValue("outcome", out var outcome)) {
           // Traiter la vérification terminée
          }
         break;
        case "check.pending": {
          // Traiter la vérification en attente
         }
         break;
        default:
         return StatusCode(400);
       }
       return StatusCode(200, receivedEvent);
      }
     }
    } catch (ComplyCube.Net.Exceptions.VerificationException) {
     return StatusCode(400);
    }
    return StatusCode(400);
   }
  }
 }
}

Vérifier manuellement

ComplyCube génère des signatures à l'aide d'un code d'authentification de message basé sur un hachage (HMAC) avec SHA-256. Bien que l'utilisation de nos bibliothèques officielles pour vérifier les signatures des événements webhook soit recommandée, vous pouvez créer une solution personnalisée en suivant ces étapes.

Extrayez le complycube-signature des en-têtes HTTP.
Déterminez la signature attendue en calculant un HMAC avec la fonction de hachage SHA256. Utilisez le secret de votre webhook comme clé, et utilisez la corps de la requête chaîne comme message.
Comparez la signature dans l'en-tête à la signature attendue.

Bonnes pratiques

Types d'événements

Vous devez configurer vos points de terminaison webhook pour ne recevoir que les types d'événements requis par votre intégration. Écouter des événements supplémentaires (ou tous les événements) mettra votre serveur sous une pression inutile et n'est pas recommandé.

Vous pouvez modifier les événements qu'un point de terminaison webhook recevra dans le tableau de bord ou via l'API.

Gérer les événements en double

Les points de terminaison webhook peuvent parfois recevoir le même événement plus d'une fois. Nous vous conseillons de vous prémunir contre les réceptions d'événements dupliqués en rendant votre traitement des événements idempotent. Une façon de procéder consiste à consigner les événements que vous avez traités et à ne pas traiter les événements déjà consignés.

Ordre des événements

ComplyCube ne garantit pas la livraison des événements dans l'ordre dans lequel ils sont générés. Votre point de terminaison ne doit pas s'attendre à recevoir les événements dans un ordre donné et doit gérer cela en conséquence. Vous pouvez également utiliser l'API pour récupérer les objets manquants.

Webhooks via HTTPS

Si vous utilisez une URL HTTPS pour votre point de terminaison webhook, ComplyCube validera que la connexion de votre serveur est sécurisée avant d'envoyer les données de votre webhook. Pour que cela fonctionne, vous devez configurer correctement votre serveur pour prendre en charge HTTPS avec un certificat serveur valide.

PrécédentGuide Postman SuivantApplication mobile