---
title: "Webhooks"
weight: 55
description: "Notifier des systèmes externes en temps réel lors des événements de présence."
---

# 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](screenshots/webhooks-formulaire.webp)

### É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

```json
{
  "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

```json
{
  "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](screenshots/webhooks-journal.webp)

## 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](/presence/permissions).