Webhooks
Recevoir des webhooks
Un abonnement envoie un POST JSON vers une URL HTTPS publique de votre choix à chaque événement sélectionné. Il se crée dans Paramètres › API et intégrations › Webhooks ; son secret whsec_… n’est affiché qu’une fois.
Message
{
"id": "6f1c…",
"type": "enrollment.created",
"version": 1,
"occurredAt": "2027-01-15T09:30:00.000Z",
"data": { "enrollmentId": 981, "userId": 42, "sessionId": 12, "trainingId": 7 }
}
Événements
| Événement | Données |
|---|---|
enrollment.created.v1 | enrollmentId, userId, sessionId, trainingId |
activity.completed.v1 | attemptId, enrollmentId, userId, sessionId, trainingId, activityId, success, score, completedAt |
webhook.test | subscriptionId (bouton « Envoyer un test ») |
Les événements d’un module (formation présentielle, certifications…) ne sont proposés que si ce module est actif pour votre organisation.
Vérifier la signature
Les messages suivent la spécification Standard Webhooks. En-têtes : webhook-id, webhook-timestamp (secondes Unix) et webhook-signature (v1,<base64>, plusieurs valeurs séparées par un espace pendant une rotation). La signature est un HMAC-SHA256, avec pour clé le secret décodé en base64 après le préfixe whsec_, du texte id.timestamp.corps.
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verify(secret, headers, rawBody) {
const id = headers['webhook-id'];
const timestamp = Number(headers['webhook-timestamp']);
if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false; // rejeu
const key = Buffer.from(secret.slice('whsec_'.length), 'base64');
const expected = Buffer.from(
'v1,' + createHmac('sha256', key).update(`${id}.${timestamp}.${rawBody}`).digest('base64'),
);
return headers['webhook-signature'].split(' ').some((candidate) => {
const value = Buffer.from(candidate);
return value.length === expected.length && timingSafeEqual(value, expected);
});
}
import base64, hashlib, hmac, time
def verify(secret: str, headers: dict, raw_body: bytes) -> bool:
msg_id, ts = headers["webhook-id"], int(headers["webhook-timestamp"])
if abs(time.time() - ts) > 300:
return False
key = base64.b64decode(secret.removeprefix("whsec_"))
digest = hmac.new(key, f"{msg_id}.{ts}.".encode() + raw_body, hashlib.sha256).digest()
expected = "v1," + base64.b64encode(digest).decode()
return any(hmac.compare_digest(expected, s) for s in headers["webhook-signature"].split(" "))
Utilisez le corps brut reçu, avant toute analyse JSON.
Reprises et désactivation
- Réponse
2xxen moins de 10 secondes : succès. Les redirections ne sont pas suivies. - Sinon, la livraison est reprise jusqu’à 8 tentatives sur environ deux heures (30 s, 1, 2, 4, 8, 16, 32 minutes puis 1 heure, avec gigue).
webhook-idreste le même entre tentatives. - Après 15 livraisons consécutives en échec définitif, ou dès une réponse
410 Gone, l’abonnement est désactivé. Un administrateur peut le réactiver après correction ; les livraisons annulées ne sont pas rejouées. - Le journal des livraisons de l’administration montre chaque tentative, son statut HTTP et sa durée.
Rotation du secret
Après rotation, l’ancien secret signe encore en parallèle pendant 24 heures : acceptez l’une ou l’autre signature le temps de déployer le nouveau secret.