Webhooks et signature
This content is not available in your language yet.
RegulaLink prévient votre serveur à chaque étape importante d’une session. Chaque requête est signée avec le signingSecret reçu à la création de la session.
Événements
Section intitulée « Événements »| Événement | Quand |
|---|---|
kyc.session.completed | La personne a terminé et envoyé le parcours. La décision peut encore être en attente (decision: "REVIEW"). |
kyc.session.decided | La décision finale est prise : automatiquement à l’envoi, ou plus tard par un agent (APPROVED ou REJECTED). |
Quand la décision est automatique, les deux événements partent l’un après l’autre, dans cet ordre.
Requête reçue
Section intitulée « Requête reçue »POST /webhooks/regulalink HTTP/1.1Content-Type: application/jsonX-RegulaLink-Event: kyc.session.decidedX-RegulaLink-Idempotency-Key: kyc.session.decided-7c1e…-1X-RegulaLink-Signature: 9f2c4b…e1a7{ "event": "kyc.session.decided", "createdAt": "2026-10-23T10:15:00.000+00:00", "data": { "sessionId": "7c1e…", "externalRef": "client-2929292", "formCode": "kyc-client-wallet", "status": "APPROVED", "decision": "APPROVED", "riskScore": 12, "submissionId": 451, "providerId": "3f0a…", "checks": [{ "code": "LIVENESS", "label": "Preuve de vivacité", "status": "PASS" }], "metadata": {}, "completedAt": "2026-10-23T10:13:42.000+00:00", "decidedAt": "2026-10-23T10:15:00.000+00:00", "decidedBy": "AGENT", "decisionReason": null }}Vérifier la signature
Section intitulée « Vérifier la signature »X-RegulaLink-Signature est le HMAC-SHA256 en hexadécimal du corps brut de la requête, avec le signingSecret de la session.
- Lisez le corps brut (octets reçus), avant tout
JSON.parse. - Retrouvez le
signingSecretde la session à partir de votreexternalRefou dusessionId. - Calculez le HMAC et comparez-le à l’en-tête avec une comparaison à temps constant.
- Répondez
2xxrapidement, puis traitez l’événement de façon asynchrone.
import crypto from "node:crypto";import express from "express";
const app = express();
// express.raw : on garde le corps brut pour la signature.app.post("/webhooks/regulalink", express.raw({ type: "application/json" }), async (req, res) => { const event = JSON.parse(req.body.toString("utf8")); const secret = await findSigningSecret(event.data.sessionId); // votre base const expected = crypto.createHmac("sha256", secret).update(req.body).digest("hex"); const received = req.get("X-RegulaLink-Signature") ?? "";
const valid = expected.length === received.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received)); if (!valid) return res.status(401).end();
res.status(204).end(); await handleEvent(event); // idempotent : voir X-RegulaLink-Idempotency-Key});import hashlib, hmac, jsonfrom flask import Flask, request, abort
app = Flask(__name__)
@app.post("/webhooks/regulalink")def regulalink_webhook(): raw = request.get_data() # corps brut event = json.loads(raw) secret = find_signing_secret(event["data"]["sessionId"]) # votre base expected = hmac.new(secret.encode(), raw, hashlib.sha256).hexdigest() if not hmac.compare_digest(expected, request.headers.get("X-RegulaLink-Signature", "")): abort(401) handle_event(event) return "", 204$raw = file_get_contents("php://input");$event = json_decode($raw, true);$secret = find_signing_secret($event["data"]["sessionId"]); // votre base$expected = hash_hmac("sha256", $raw, $secret);$received = $_SERVER["HTTP_X_REGULALINK_SIGNATURE"] ?? "";
if (!hash_equals($expected, $received)) { http_response_code(401); exit;}http_response_code(204);handle_event($event);@PostMapping("/webhooks/regulalink")public ResponseEntity<Void> webhook(@RequestBody byte[] raw, @RequestHeader("X-RegulaLink-Signature") String received) throws Exception { JsonNode event = mapper.readTree(raw); String secret = findSigningSecret(event.path("data").path("sessionId").asText()); Mac mac = Mac.getInstance("HmacSHA256"); mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256")); String expected = HexFormat.of().formatHex(mac.doFinal(raw)); if (!MessageDigest.isEqual(expected.getBytes(), received.getBytes())) { return ResponseEntity.status(401).build(); } handleEvent(event); return ResponseEntity.noContent().build();}Tester une signature
Section intitulée « Tester une signature »Collez un webhook reçu et son secret pour vérifier votre implémentation.
Le calcul est fait dans votre navigateur. Aucune donnée n'est envoyée.
Reprises et idempotence
Section intitulée « Reprises et idempotence »- Un envoi est considéré comme livré quand votre serveur répond 2xx (délai maximal : 10 secondes).
- En cas d’échec, RegulaLink réessaie après 5 secondes puis 30 secondes.
- La même notification peut arriver plusieurs fois : utilisez
X-RegulaLink-Idempotency-Keypour ignorer les doublons. - Les échecs de livraison sont visibles dans la console (KYC → Liens de vérification, onglet de la session) et peuvent être relancés depuis l’admin.
Redirection signée
Section intitulée « Redirection signée »Si la session a un redirectUrl, la personne y est renvoyée à la fin avec ces paramètres :
https://votre-app.com/kyc/retour ?kyc_session_id=7c1e… &status=SUBMITTED &decision=REVIEW &external_ref=client-2929292 &ts=1761214500 &signature=5ab0…signature = HMAC-SHA256 (hex) de la chaîne kyc_session_id.status.external_ref.ts (séparateur .), avec le même signingSecret.