Aller au contenu principal
Version: Next

Configuration des Webhooks

Ce guide explique comment configurer vos webhooks dans la plateforme Beedeez pour recevoir des notifications d'événements en temps réel.

Accès à la Configuration​

Les webhooks se configurent via le back office Beedeez. Vous aurez besoin de privilèges administrateur pour accéder et gérer ces paramètres.

Créer un Webhook​

Pour créer un nouveau webhook, vous devrez fournir les informations suivantes :

Champs Obligatoires​

Nom​

Un nom explicite pour identifier ce webhook. Cela facilite la gestion de plusieurs webhooks.

Exemple : "Notifications de Certificats Production" ou "Intégration Système RH"

URL​

L'URL HTTPS où Beedeez enverra les notifications webhook. Cette URL doit être publiquement accessible et capable de recevoir des requêtes POST.

Exigences :

  • Doit utiliser HTTPS (HTTP n'est pas supporté pour des raisons de sécurité)
  • Doit être publiquement accessible
  • Doit répondre dans les 5 secondes (configurable)
  • Doit retourner un code de statut HTTP 2xx pour une réception réussie

Exemple : https://api.votreentreprise.com/webhooks/beedeez

Types d'Événements​

Sélectionnez quels événements doivent déclencher ce webhook. Vous pouvez vous abonner à un ou plusieurs types d'événements. Consultez la Référence des Types d'Événements pour une liste complète.

Événements Actuellement Disponibles :

  • certificate_completed - Lorsqu'un utilisateur obtient un certificat
  • certificate_expired - Lorsqu'un certificat expire

Exemple : ["certificate_completed", "certificate_expired"]

Configuration Optionnelle​

Activé​

Basculer pour activer ou désactiver le webhook sans supprimer la configuration.

Par défaut : true

Timeout (ms)​

Temps maximum en millisecondes d'attente de réponse avant de considérer la requête comme échouée.

Par défaut : 5000 (5 secondes) Plage : 1000-30000 ms

En-têtes Personnalisés​

En-têtes HTTP supplémentaires à inclure avec chaque requête webhook. Utile pour passer des clés API, des IDs de corrélation ou d'autres métadonnées.

Exemple :

{
    "X-Custom-ID": "votre-identifiant",
    "X-Environment": "production"
}

Authentification​

Configurez comment Beedeez doit s'authentifier auprès de votre serveur. Consultez Options d'Authentification pour plus de détails.

Méthodes Disponibles :

  • Aucune (non recommandé pour la production)
  • Bearer Token
  • Authentification Basic
  • Clé API
  • En-tête Personnalisé

Exemple de Configuration​

Voici un exemple complet de configuration d'un webhook :

{
    "name": "Webhook Certificats Production",
    "url": "https://api.votreentreprise.com/webhooks/beedeez/certificats",
    "enabled": true,
    "eventTypes": ["certificate_completed", "certificate_expired"],
    "auth": {
        "authType": "bearer_token",
        "token": "votre-token-bearer-secret"
    },
    "timeoutMs": 5000,
    "customHeaders": {
        "X-Webhook-Source": "beedeez",
        "X-Environment": "production"
    }
}

Livraison des Webhooks​

Format de Requête​

Beedeez envoie les notifications webhook sous forme de requêtes HTTP POST avec :

  • Méthode : POST
  • Content-Type : application/json
  • Body : Payload JSON contenant les données de l'événement
  • Headers : En-têtes d'authentification + en-têtes personnalisés

Exigences de Réponse​

Votre serveur doit :

  1. Répondre Rapidement : Retourner une réponse dans le délai configuré (5 secondes par défaut)
  2. Retourner un Statut de Succès : Retourner un code HTTP 2xx (200-299) pour confirmer la réception
  3. Gérer l'Idempotence : Être capable de recevoir le même événement plusieurs fois sans effet de bord

Exemple de Réponse Réussie :

HTTP/1.1 200 OK
Content-Type: application/json

{
  "received": true,
  "message": "Webhook traité avec succès"
}

Logique de Réessai​

Si votre serveur ne répond pas correctement, Beedeez réessaie automatiquement l'envoi du webhook :

  • Tentatives Maximum : 100 réessais
  • Intervalle de Réessai : 6 secondes fixes entre les tentatives
  • Durée Totale de Réessai : Jusqu'à 10 minutes
  • Conditions de Réessai : Tout code de statut HTTP en dehors de la plage 2xx ou timeout réseau

Comportement de Réessai :

  • 1er réessai : Après 6 secondes
  • 2ème réessai : Après 12 secondes
  • 3ème réessai : Après 18 secondes
  • ... continue toutes les 6 secondes jusqu'à 100 tentatives

Configuration de la File d'Attente​

Les webhooks sont traités via un système de file d'attente dédié :

  • Concurrence : Jusqu'à 5 requêtes webhook parallèles
  • Nom de la File : webhook-notification
  • Traitement : Asynchrone avec réessai automatique

Bonnes Pratiques​

Sécurité​

  • ✅ Utilisez toujours HTTPS
  • ✅ Implémentez une authentification (Bearer token ou clé API recommandés)
  • ✅ Validez les signatures de webhook si disponibles
  • ✅ Restreignez l'accès aux adresses IP de Beedeez si possible

Fiabilité​

  • ✅ Concevez des gestionnaires idempotents
  • ✅ Conservez les événements webhook pour audit et rejeu
  • ✅ Ne retournez un code 2xx qu'après un traitement réussi
  • ✅ Utilisez une file d'attente ou un job asynchrone pour les opérations longues

Performance​

  • ✅ Répondez dans les 5 secondes
  • ✅ Traitez les webhooks de manière asynchrone
  • ✅ Surveillez la santé du point de terminaison webhook
  • ✅ Configurez des alertes pour les webhooks échoués

Tests​

  • ✅ Testez avec des charges utiles d'exemple avant la mise en production
  • ✅ Vérifiez que l'authentification fonctionne correctement
  • ✅ Testez le comportement de réessai en simulant des échecs
  • ✅ Surveillez les logs pendant les premiers jours après la configuration

Surveillance du Statut des Webhooks​

La configuration des webhooks suit les statistiques de livraison :

  • Créé Le : Quand le webhook a été configuré
  • Dernier Déclenchement : Horodatage de la livraison webhook la plus récente
  • Nombre de Succès : Nombre de livraisons réussies
  • Nombre d'Échecs : Nombre de livraisons échouées (après tous les réessais)

Surveillez ces métriques pour vous assurer que vos webhooks fonctionnent correctement.

Dépannage​

Les Webhooks ne Sont pas Reçus​

  1. Vérifiez l'Accessibilité du Point de Terminaison : Assurez-vous que votre URL est publiquement accessible via HTTPS
  2. Vérifiez les Types d'Événements : Confirmez que vous êtes abonné aux bons types d'événements
  3. Vérifiez le Statut Activé : Assurez-vous que le webhook est activé
  4. Vérifiez l'Authentification : Vérifiez que les identifiants d'authentification sont corrects
  5. Vérifiez les Règles de Pare-feu : Assurez-vous que votre pare-feu autorise les requêtes entrantes de Beedeez

Timeouts des Webhooks​

  1. Optimisez le Temps de Réponse : Assurez-vous que votre point de terminaison répond dans la période de timeout
  2. Utilisez le Traitement en Arrière-Plan : Déplacez le traitement lourd vers des jobs en arrière-plan
  3. Augmentez le Timeout : Ajustez le paramètre de timeout si nécessaire (jusqu'à 30 secondes)
  4. Vérifiez les Ressources Serveur : Assurez-vous que votre serveur dispose de ressources adéquates

Webhooks Dupliqués​

C'est un comportement attendu dû à la logique de réessai. Concevez votre gestionnaire de webhook pour être idempotent :

  • Utilisez des IDs d'événement uniques pour détecter les doublons
  • Stockez les IDs de webhook traités dans une base de données
  • Ignorez le traitement si l'événement a déjà été géré

Prochaines Étapes​