Guides
Webhook d’inscription historique
POST /v1/webhooks/users reste servi pour les intégrations existantes. Il crée ou met à jour un apprenant, l’inscrit à une diffusion et lui envoie l’invitation.
{ "email": "ada@example.org", "firstname": "Ada", "lastname": "Lovelace", "sessionId": "12" }
Changements pour les intégrateurs existants
Le chemin, la méthode, le corps de la requête et la réponse de succès (201, corps vide) sont inchangés. Les règles suivantes s’appliquent désormais :
| Situation | Avant | Désormais |
|---|---|---|
| Compte désactivé ou supprimé | Réactivé | 409 account_suspended, compte inchangé |
| Compte géré par une source d’identité (SCIM) | Mis à jour | 409 account_managed |
| Adresse e-mail invalide | Souvent acceptée | 400 validation_failed, 255 caractères au plus |
| Prénom ou nom omis | Effacé sur un compte existant | Conservé |
| Diffusion inconnue | 400 | 400 session_not_found |
| Corps d’erreur | Message texte | application/problem+json, avec un code stable |
| Jeton absent ou inconnu | 401 | 401 invalid_token |
| Organisation désactivée ou fonctionnalité fermée | Accepté | 403 module_unavailable |
| Plus de 600 requêtes par minute | Accepté | 429 rate_limited avec Retry-After |
| Service momentanément indisponible | 400 | 503 temporarily_unavailable avec Retry-After |
| Échec d’envoi de l’invitation | Création annulée | Compte et inscription conservés ; l’invitation se renvoie depuis l’administration |
Également :
- chaque réponse obtenue avec le jeton historique porte l’en-tête
Deprecation; - un jeton OAuth avec les scopes
users:writeetenrollments:writeest accepté sur ce chemin ; - l’en-tête facultatif
Idempotency-Keyévite un second envoi d’invitation lors d’un rejeu. Sans lui, un rejeu inscrit sans doublon et renvoie l’invitation, comme avant.
À vérifier de votre côté : traitez 409 comme un refus définitif à signaler à un administrateur, 429 et 503 comme des erreurs temporaires à réessayer après Retry-After, et lisez le champ code plutôt que le texte du message.
Migrer
- Faites créer un client d’intégration avec
users:writeetenrollments:write. - Obtenez un jeton par
client_credentials. - Remplacez l’appel par
POST /api/v1/enrollments:
{ "sessionId": 12, "user": { "email": "ada@example.org", "firstname": "Ada", "lastname": "Lovelace" }, "invite": true }
- Demandez la suppression du jeton historique une fois la bascule faite.
Une date de fin de service sera annoncée par l’en-tête Sunset lorsque les organisations concernées auront migré.