Skip to content

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énementQuand
kyc.session.completedLa personne a terminé et envoyé le parcours. La décision peut encore être en attente (decision: "REVIEW").
kyc.session.decidedLa 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.

POST /webhooks/regulalink HTTP/1.1
Content-Type: application/json
X-RegulaLink-Event: kyc.session.decided
X-RegulaLink-Idempotency-Key: kyc.session.decided-7c1e…-1
X-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
}
}

X-RegulaLink-Signature est le HMAC-SHA256 en hexadécimal du corps brut de la requête, avec le signingSecret de la session.

  1. Lisez le corps brut (octets reçus), avant tout JSON.parse.
  2. Retrouvez le signingSecret de la session à partir de votre externalRef ou du sessionId.
  3. Calculez le HMAC et comparez-le à l’en-tête avec une comparaison à temps constant.
  4. Répondez 2xx rapidement, 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
});

Collez un webhook reçu et son secret pour vérifier votre implémentation.

Saisissez le secret et l'en-tête pour vérifier.

Le calcul est fait dans votre navigateur. Aucune donnée n'est envoyée.

  • 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-Key pour 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.

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.