Aller au contenu principal
Version: Next

Référence des Types d'Événements

Cette page fournit une référence complète de tous les types d'événements webhook disponibles dans la plateforme Beedeez. Chaque type d'événement représente une action spécifique ou un changement d'état qui peut déclencher une notification webhook.

Événements Actuellement Supportés​

Beedeez supporte actuellement les notifications webhook pour les événements liés aux certificats. Des types d'événements supplémentaires seront ajoutés dans les versions futures.

Événements de Certificat​

certificate_completed​

Déclenché lorsqu'un utilisateur complète avec succès un certificat (badge) sur la plateforme.

Quand Cet Événement se Déclenche :

  • L'utilisateur complète toutes les exigences pour un certificat
  • Le certificat est automatiquement attribué à l'utilisateur
  • Le certificat est manuellement attribué par un administrateur

La Charge Utile Contient :

  • Détails complets du certificat (badge)
  • Informations sur l'utilisateur
  • Date de complétion
  • Activités de leçon validantes
  • Date d'expiration (si applicable)

Cas d'Usage :

  • Notifier les systèmes RH des certifications des employés
  • Mettre à jour les dossiers d'apprentissage externes
  • Déclencher des workflows de récompense ou de reconnaissance
  • Générer des rapports de conformité

Exemple de Scénario :

1. L'utilisateur complète toutes les leçons d'un parcours "Formation Sécurité"
2. Le système attribue le badge "Certifié Sécurité" à l'utilisateur
3. Le webhook se déclenche avec l'événement certificate_completed
4. Votre système reçoit la notification et met à jour les dossiers des employés

certificate_expired​

Déclenché lorsqu'un certificat expire en raison de la fin de sa période de validité.

Quand Cet Événement se Déclenche :

  • Le certificat atteint sa date d'expiration
  • Le système traite les certificats expirés (généralement via un job planifié)
  • Un email de rappel d'expiration est envoyé à l'utilisateur

La Charge Utile Contient :

  • Détails complets du certificat (badge)
  • Informations sur l'utilisateur
  • Date de complétion originale
  • Date d'expiration
  • Statut du badge

Cas d'Usage :

  • Notifier les utilisateurs pour renouveler les certifications
  • Mettre à jour les systèmes de suivi de conformité
  • Déclencher des workflows de re-certification
  • Alerter les managers des certifications d'équipe expirées

Exemple de Scénario :

1. L'utilisateur a complété "Certification Premiers Secours" il y a 1 an
2. Le certificat a une période de validité de 365 jours
3. Le système détecte que le certificat a expiré
4. Le webhook se déclenche avec l'événement certificate_expired
5. Votre système déclenche une notification de re-certification

Abonnement aux Événements​

Lors de la configuration d'un point de terminaison webhook, vous pouvez vous abonner à un ou plusieurs types d'événements. Chaque point de terminaison webhook peut avoir sa propre liste d'abonnement aux événements.

Exemple de Configuration :

{
    "name": "Notifications de Certificats",
    "url": "https://api.votreentreprise.com/webhooks/certificats",
    "eventTypes": ["certificate_completed", "certificate_expired"]
}

Filtrage des Événements​

Les webhooks sont filtrés au niveau de l'organisation :

  1. Vérification de l'Organisation : Le système vérifie si l'organisation a des points de terminaison webhook configurés
  2. Correspondance du Type d'Événement : Seuls les points de terminaison abonnés au type d'événement spécifique sont déclenchés
  3. Statut Activé : Seuls les points de terminaison activés reçoivent des notifications
  4. Livraison : La notification webhook est envoyée aux points de terminaison correspondants

Logique de Filtrage :

// Pseudo-code montrant la logique de filtrage
const endpoints = memberConfig.webHookConfig.endpoints.filter((endpoint) => {
    return endpoint.enabled && endpoint.eventTypes.includes(eventType);
});

Structure de la Charge Utile d'Événement​

Tous les événements webhook suivent une structure de charge utile cohérente. Les champs exacts dépendent du type d'événement, mais incluent généralement :

Champs Communs​

  • Métadonnées d'Événement : Informations sur l'événement lui-même
  • Données d'Organisation : Identifiants du propriétaire/organisation
  • Données d'Entité : L'entité principale liée à l'événement (certificat, utilisateur, leçon, etc.)
  • Entités Liées : Données associées (infos utilisateur, détails de leçon, etc.)

Charge Utile d'Événement de Certificat​

Pour les événements de certificat (certificate_completed et certificate_expired), la charge utile contient le document BadgeUser complet, qui inclut :

{
    "_id": "badge_user_id",
    "_userId": "user_id",
    "_ownerId": "organization_id",
    "_badgeId": "badge_definition_id",
    "creationDate": "2024-11-27T10:30:00.000Z",
    "expires": "2025-11-27T10:30:00.000Z",
    "disabled": false,
    "expiryReminderSent": false,
    "_lessonActiveIds": ["lesson_active_1", "lesson_active_2"],
    "ruleData": {
        // Données spécifiques à la règle du badge
    },
    "createdAt": "2024-11-27T10:30:00.000Z",
    "updatedAt": "2024-11-27T10:30:00.000Z"
}

Consultez Exemples de Charges Utiles pour des exemples complets et réels de charges utiles.

Garanties de Livraison des Événements​

Livraison Au-Moins-Une-Fois​

Beedeez garantit une livraison au-moins-une-fois pour les événements webhook :

  • Les événements seront livrés au moins une fois à votre point de terminaison
  • En raison de la logique de réessai, vous pouvez recevoir le même événement plusieurs fois
  • Concevez votre gestionnaire de webhook pour être idempotent

Ordre​

  • Les événements sont traités de manière asynchrone via un système de file d'attente
  • Les événements sont généralement livrés dans l'ordre où ils se produisent
  • Cependant, un ordre strict n'est pas garanti, surtout pendant les réessais
  • Utilisez les champs de date dans la charge utile (comme createdAt, updatedAt, creationDate) pour déterminer la séquence réelle des événements

Fiabilité​

  • Les livraisons échouées sont automatiquement réessayées (jusqu'à 100 tentatives sur 10 minutes)
  • Les webhooks sont traités avec une concurrence de 5 requêtes parallèles
  • Le système de file d'attente assure une livraison fiable même en cas de charge élevée

Test des Événements​

Pour tester votre intégration webhook :

  1. Créez des Certificats de Test : Configurez des certificats de test dans un environnement de développement
  2. Attribuez des Certificats de Test : Attribuez manuellement des certificats à des utilisateurs de test
  3. Déclenchez l'Expiration : Créez des certificats avec de courtes périodes de validité
  4. Surveillez les Logs : Vérifiez les logs de votre point de terminaison webhook pour les événements reçus
  5. Vérifiez la Charge Utile : Assurez-vous que la structure de la charge utile correspond à vos attentes

Surveillance des Événements​

Surveillez la livraison des événements webhook via :

  • Statistiques des Webhooks : Compteurs de succès/échec dans le back office
  • Logs d'Application : Logs détaillés du traitement des webhooks
  • Logs de Votre Point de Terminaison : Suivez les webhooks reçus de votre côté
  • Outils de Surveillance : Utilisez des outils APM pour suivre les performances des webhooks

Prochaines Étapes​