Webhooks de l'API d'intégration
Un webhook est une notification automatique qu’Eduvem envoie à un autre système dès que quelque chose se produit - sans que ce système ait besoin de demander en permanence « et maintenant, quelque chose a changé ? ». Avec les webhooks, lorsque l’inscription d’un Participant change de statut, qu’il reçoit un certificat ou qu’il termine un parcours, Eduvem « pousse » cette information immédiatement vers l’adresse indiquée par votre équipe d’intégration (le service RH, un BI, un système interne).
C’est l’alternative « en temps réel » à l’interrogation périodique : au lieu que votre système demande de temps en temps ce qui a changé, Eduvem prévient d’elle-même au moment où le changement se produit.
À qui s’adresse cette fonctionnalité
Section intitulée « À qui s’adresse cette fonctionnalité »Configurer des webhooks implique deux personnes aux rôles différents :
- L’administrateur de l’institution (vous) accorde la permission sur un jeton d’API. C’est ce que couvre cet article.
- Votre équipe d’intégration (les développeurs) utilise ce jeton pour enregistrer les adresses qui recevront les notifications et pour traiter chaque notification reçue. Cette partie technique se trouve dans la documentation de l’API.
Accorder la permission de webhooks sur un jeton
Section intitulée « Accorder la permission de webhooks sur un jeton »Les webhooks se gèrent avec les mêmes jetons d’API que le reste de l’intégration - il n’y a pas d’identifiant distinct. La capacité de gérer les webhooks est protégée par une permission spécifique, qui est désactivée par défaut : webhooks:manage.
- Dans le panneau d’administration, ouvrez l’onglet Intégrations de l’institution.
- Créez un nouveau jeton d’API (voir Jetons de l’API d’intégration). Si l’intégration a déjà un jeton, vous pouvez aussi y activer la permission avec le bouton Modifier les permissions de la liste des jetons, sans créer de nouveau jeton.
- Dans la liste des permissions (portées) du jeton, cochez Webhooks (gérer) et Rapports (lecture) - s’abonner à un événement, quel qu’il soit, exige les deux permissions ensemble.
- Confirmez avec OK et copiez la valeur du jeton affichée - elle ne sera plus montrée.
Un jeton sans la permission Webhooks qui tente de gérer des webhooks reçoit un refus d’accès. Créer ou mettre à jour un abonnement exige aussi la permission Rapports (lecture) en plus de Webhooks - sans elle, l’appel est refusé même avec Webhooks cochée ; lister, tester et supprimer des abonnements n’exigent pas Rapports. Accorder à un jeton la permission de lire les participants et les inscriptions n’accorde pas, à elle seule, la permission de webhooks - elle doit être cochée explicitement. Comme toujours, n’accordez à un jeton que ce que l’intégration utilise réellement.
Les notifications sont liées au jeton qui a créé ou mis à jour en dernier l’enregistrement du webhook. Si vous retirez la permission Rapports (lecture) de ce jeton, ou si vous le supprimez, ses webhooks cessent d’envoyer des notifications et apparaissent avec le statut tokenRevoked ; les événements de cette période ne sont pas renvoyés ensuite. Pour reprendre, l’équipe d’intégration doit réactiver le webhook avec un jeton qui possède les deux permissions. Pour remplacer un jeton, créez le nouveau, réactivez chaque webhook avec lui, puis supprimez l’ancien.
Ce que transportent les notifications (vue d’ensemble)
Section intitulée « Ce que transportent les notifications (vue d’ensemble) »Chaque notification est un message signé, envoyé à l’adresse enregistrée par votre équipe, indiquant l’événement (par exemple, « changement de statut de l’inscription », « certificat délivré » ou « parcours terminé ») et les données associées : l’inscription, la salle, le contenu et le participant. Une notification de parcours terminé est différente : elle transporte le participant et le parcours (identifiant et nom), sans inscription, salle ni contenu - un parcours réunit plusieurs salles, donc la notification n’est pas liée à une seule d’entre elles. Tout est isolé par institution - une notification ne transporte que les données de l’institution propriétaire du jeton.
L’envoi du CPF dans la notification suit la configuration de profil de votre institution : si le champ CPF n’est pas activé dans le profil, il n’est pas envoyé.
Quand la personne a un externalId (le code du système RH chargé par la synchronisation des personnes), le bloc de la personne de la notification contient aussi person.externalId ; sans lui, la clé n’apparaît pas et la notification reste comme avant. Voir Documentation de l’API.
Les détails techniques sont dans la documentation de l’API
Section intitulée « Les détails techniques sont dans la documentation de l’API »L’enregistrement des adresses qui reçoivent les notifications, le catalogue complet des événements, la vérification de la signature de sécurité, la politique de nouvelles tentatives et le suivi des livraisons sont réalisés par l’équipe d’intégration et sont décrits dans la documentation de l’API. Transmettez ce support aux personnes qui développeront l’intégration.