Webhooks

Webhooks

Les webhooks permettent de notifier en temps réel des systèmes externes (CRM, plateforme LMS, outil de reporting, Slack, etc.) lorsque des événements importants se produisent dans le module Présence : création d'une session, signature enregistrée, clôture, etc.

Un webhook est un appel HTTP POST que le serveur Dolibarr envoie automatiquement à une URL que vous définissez, avec en charge utile (JSON) les informations sur l'événement.

Configurer un webhook

Créer un webhook

  1. Dans le menu principal, cliquez sur Présence > Webhooks. Cette entrée n'est visible que pour les administrateurs.
  2. Cliquez sur Nouveau webhook.
  3. Renseignez :
    • Libellé : nom interne pour reconnaître le webhook.
    • URL : URL HTTP/HTTPS du système distant qui doit recevoir les notifications.
    • Secret (recommandé) : chaîne secrète utilisée pour signer les requêtes (signature HMAC-SHA256). Le système distant peut vérifier la signature pour s'assurer que la requête vient bien de votre Dolibarr.
    • Événements : cochez les types d'événements qui déclenchent ce webhook.
  4. Cliquez sur Enregistrer.

Formulaire de création d'un webhook avec les options d'événements

Événements disponibles

Événement Déclenché quand
session.created Une session est créée
session.validated Une session passe à l'état Validée
session.closed Une session est clôturée
session.cancelled Une session est annulée
attendee.added Un participant est ajouté à une session
attendee.removed Un participant est retiré d'une session
signature.recorded Un participant signe

Format de la charge utile

La requête est envoyée en POST au format JSON. Le contenu varie selon l'événement.

Exemple : signature enregistrée

{
  "event": "signature.recorded",
  "timestamp": "2026-04-29T14:32:08+02:00",
  "data": {
    "signature_id": 142,
    "presence_status": "present",
    "time_slot": "morning",
    "signed_at": "29/04/2026 14:32",
    "attendee_name": "Marie Dupont",
    "attendee_email": "marie.dupont@exemple.fr",
    "session_id": 38,
    "session_ref": "PRES-20260429-00001",
    "session_label": "Formation PHP - Jour 1",
    "date_session": "29/04/2026"
  }
}

Exemple : session créée

{
  "event": "session.created",
  "timestamp": "2026-04-15T09:00:00+02:00",
  "data": {
    "session_id": 38,
    "session_ref": "PRES-20260429-00001",
    "session_label": "Formation PHP - Jour 1",
    "session_type": "training",
    "date_session": "29/04/2026",
    "time_slot": "fullday",
    "location": "Salle 1, Paris",
    "status": 0,
    "project_ref": "FORMATION-PHP-2026",
    "project_title": "Cycle de formation PHP printemps 2026"
  }
}

Signature HMAC

Si vous avez défini un secret, chaque requête contient un en-tête HTTP :

X-Presence-Signature: sha256=<hash_hexadecimal>

Le hash est calculé en HMAC-SHA256 sur le corps brut de la requête, avec le secret comme clé. Côté receveur, recalculez le HMAC sur le corps reçu et comparez : si les deux correspondent, la requête vient bien de votre Dolibarr et n'a pas été altérée.

Suivi et journal des appels

Chaque webhook conserve un journal des derniers appels effectués. Pour consulter ce journal :

  1. Ouvrez la fiche du webhook.
  2. Cliquez sur l'onglet Journal des appels.

Le journal affiche pour chaque appel :

  • Date et heure.
  • Événement déclencheur.
  • Code HTTP de réponse du système distant.
  • Durée de l'appel.
  • Tronqué du corps de la réponse (utile pour diagnostiquer un échec).

Journal des appels d'un webhook avec les statuts de chaque tentative

Ré-essais et tolérance aux pannes

Si le système distant ne répond pas (timeout) ou répond avec un code d'erreur (4xx ou 5xx), l'appel est considéré comme échoué mais n'est pas réessayé automatiquement par défaut.

Pour activer un mécanisme de relance :

  • Activez le réglage Ré-essai automatique dans la fiche du webhook.
  • Définissez le nombre maximum de tentatives et le délai entre chaque.

Désactiver temporairement un webhook

Depuis la liste des webhooks, vous pouvez désactiver un webhook sans le supprimer (par exemple pendant la maintenance du système distant). Les événements survenus pendant la désactivation ne sont pas rejoués lors de la réactivation.

Cas d'usage typiques

  • Notifier un canal Slack quand une session de formation démarre.
  • Mettre à jour un CRM quand un participant signe (mise à jour automatique de la fiche client).
  • Alimenter un tableau de bord externe des présences.
  • Envoyer une notification mobile au formateur dès qu'un stagiaire arrive et signe.
  • Synchroniser une plateforme LMS avec les signatures collectées.

Étape suivante

Pour comprendre les permissions du module et savoir qui peut faire quoi, consultez la page Permissions.

Import ICS et calendrier FAQ