Webhooks

Recevez un rappel HTTP signé dès que quelque chose se passe dans votre organisation, au lieu d'interroger l'API en boucle.

Vue d'ensemble

Un point de webhook est une URL à vous qu'EduShell appelle en chaque fois qu'un événement auquel vous êtes abonné se produit. Enregistrez-en un dans Administration > Webhooks : saisissez l'URL, choisissez les événements, et EduShell affiche un secret de signature une seule fois (il ressemble à ). Conservez-le, il vous servira à vérifier les livraisons.

Chaque livraison est réessayée en cas d'échec et consignée dans un journal de livraison que vous pouvez inspecter et rejouer.

Événements

Abonnez-vous à l'un de ces types d'événements :

Événement	Déclenché quand
	Le rôle d'un membre change
	Un membre est retiré
	La propriété de l'org est transférée
	Les paramètres de l'organisation changent
	L'organisation est fermée
	Une connexion OIDC est supprimée
	Une connexion SAML est supprimée
	Un enregistrement LTI est supprimé
	Une clé API est créée
	Une clé API est révoquée
	Un point de webhook est créé
	Un point de webhook est supprimé

Charge utile

EduShell envoie un corps JSON en . L'enveloppe est la même pour chaque événement ; porte les champs propres à l'événement :

json

{
  "id": "a3f1c9e2-7b40-4c1a-9e6d-2b8f0a1c4d5e",
  "event": "member.removed",
  "org_id": "3d2c1b0a-9f8e-7d6c-5b4a-3c2d1e0f9a8b",
  "occurred_at": "2026-07-29T14:12:05Z",
  "data": { "user_id": "7c6b5a49-2f10-4e8b-b1a2-6d5c4b3a2f10" }
}

Chaque requête porte aussi des en-têtes :

En-tête	Valeur
	Le type d'événement, par exemple
	Un identifiant de livraison unique (à utiliser pour dédupliquer)
	suivi du HMAC du corps

Répondez avec un statut pour accuser réception. Tout le reste, ou un dépassement de délai, compte comme un échec et est réessayé.

Vérifier la signature

Chaque livraison est signée pour que vous puissiez lui faire confiance. L'en-tête est suivi du HMAC-SHA256 hexadécimal du corps brut de la requête, avec le secret de signature de votre point d'accès comme clé. Calculez le même HMAC et comparez, avec une comparaison à temps constant.

func verify(secret string, body []byte, header string) bool {
  mac := hmac.New(sha256.New, []byte(secret))
  mac.Write(body)
  expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))
  return hmac.Equal([]byte(expected), []byte(header))
}

javascript

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret, body, header) {
  const digest = createHmac("sha256", secret).update(body).digest("hex");
  const expected = `sha256=${digest}`;
  return expected.length === header.length &&
    timingSafeEqual(Buffer.from(expected), Buffer.from(header));
}

python

import hashlib, hmac

def verify(secret: str, body: bytes, header: str) -> bool:
    digest = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={digest}", header)

Signez sur les octets bruts du corps de la requête, avant tout parsing ou re-sérialisation JSON. Parser puis ré-encoder peut changer les espaces ou l'ordre des clés et casser la signature.

Réessais et journal de livraison

Si votre point d'accès ne renvoie pas de , ou dépasse le délai, EduShell réessaie avec un backoff exponentiel (à partir d'environ 30 secondes, en doublant jusqu'à un plafond, plusieurs fois sur environ une journée). Pour rester correct sous les réessais, rendez votre gestionnaire idempotent : dédupliquez sur .

Chaque tentative est consignée dans le journal de livraison sous le point d'accès, avec le code de réponse et le minutage. Vous pouvez renvoyer une livraison à la main, et faire tourner le secret de signature (le nouveau secret est affiché une seule fois). Faites-le tourner sans attendre si vous soupçonnez une fuite du secret.