Aller au contenu

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énementDonnées
enrollment.created.v1enrollmentId, userId, sessionId, trainingId
activity.completed.v1attemptId, enrollmentId, userId, sessionId, trainingId, activityId, success, score, completedAt
webhook.testsubscriptionId (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 2xx en 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-id reste 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.