Diagnostiquer Dolibarr : webhooks Plan d’action pour passer à l’échelle

Par [Nom du·de l’auteur·e]
Date : 3 novembre 2025

1. Introduction

Dolibarr est un ERP/CRM open‑source très répandu qui propose, parmi ses nombreuses fonctionnalités, un système de webhooks (ou hooks) permettant d’automatiser des actions externes (notifications Slack, mise à jour d’une plateforme de facturation, synchronisation avec un CRM, etc.).

Cependant, lorsqu’une organisation beginne à exploiter massivement ces webhooks — plusieurs dizaines voire plusieurs centaines d’appels par jour — des limites apparaissent : délai de réponse, fiabilité, sécurité, visibilité opérationnelle, ou encore capacité de traitement parallèle.

Cet article passe en revue :

  1. Les points de diagnostic à identifier chez Dolibarr lorsqu’on utilise les webhooks.

  2. Un plan d’action concret pour passer à l’échelle, en gardant la robustesse et la conformité aux bonnes pratiques.

2. Diagnostic de l’utilisation des webhooks dans Dolibarr | Domaine | Questions clés à se poser | Symptômes typiques |

|——–|————————–|——————–|
| 1️⃣ Architecture technique | – Les webhooks sont‑ils exposés via cron ou listen HTTP ?
– Quelle version de PHP/PHP‑FPM/Docker est utilisée ?
– Le serveur est‑il scalable (scaling‑out) ? | – Temps de réponse > 5 s
– Timeout du worker PHP‑FPM
– “504 Gateway Timeout” sur le serveur web externe |
| 2️⃣ Performance | – Combien de webhooks sont déclenchés par événement ?
– Le temps moyen d’exécution du script (via hookclient.php) ?
– Le chargeur de requêtes (NGINX/Apache) est‑il dimensionné ? | – Augmentation du temps de traitement lors de pics (ex. : fin de mois comptable)
– Utilisation CPU > 80 % sur le serveur |
| 3️⃣ Fiabilité & Monitoring | – Existe‑t‑il un mécanisme de retry ou de DLQ ?
– Les logs sont‑ils centralisés ?
– Des alertes sont‑elles configurées (Grafana, Prometheus, etc.) ? | – Événements perdus sanstrace
– Absence d’alertes, difficulté à identifier les anomalies |
| 4️⃣ Sécurité | – Les webhooks sont‑ils protégés par un secret token ?
– Les appels sortants utilisent‑ils TLS ?
– Est‑il possible d’héberger des scripts malveillants via un webhook ? | – Acceptation de requêtes non authentifiées → fuite de données
– Exposition d’une URL interne seule accessible par le réseau interne |
| 5️⃣ Qualité du code | – Le script hookclient.php est‑il bien structuré (tests unitaires, separation des responsabilités) ?
– Gestion des erreurs : catch, backoff, circuit‑breaker ?
– Documenté‑t‑il les paramètres attendus ? | – Reprises de code “à la main” → bugs récurrents
– Absence de logs structurés → difficulté de debugging |
| 6️⃣ Concurrence | – Combien de webhooks peuvent être traités en parallèle ?
– Utilise‑t‑on un worker unique ou plusieurs processus ? | – Embouteillage quand plusieurs événements simultanés (ex. : import de devis) |

À noter : Dans Dolibarr, les webhooks sont généralement implémentés via le module httprequest ou le hookclient.php intégré. Ce point d’entrée doit être examiné avec attention lors du diagnostic initial.

3. Plan d’action pour passer à l’échelle

Étape 0 – Pré‑requis & état des lieux

Action Outils/Sources Résultat attendu
Audit de l’infrastructure docker-compose, systemctl, Grafana/Docker stats Cartographie du nombre de workers PHP‑FPM, ressources CPU/RAM
Extraction des métriques prometheus-client (ou mod_expires) → compteur d’appels webhook, latence Baseline : requests/sec, temps moyen, taux d’erreur
Recensement des webhooks Script list_webhooks.php (ou interrogation de la table hooks via php CLI) Nombre d’URL actives, fréquence prévue, type de destinataire (ex. : external‑payments, Slack)
Analyse sécurité Outil OWASP ZAP ou Burp Suite pour tester les endpoints Confirmation de l’utilisation de secret token + TLS

Étape 1 – Refactorisation du traitement des webhooks

  1. Passer à un modèle asynchrone

    • De : le script HTTP s’exécute dans le même processus PHP qui répond à la requête frontale.

    • À : publier un message sur une file d’attente (ex. : RabbitMQ, Redis Streams, Kafka) et laisser un worker dédié le consommer.

    • Avantages : réduction du temps de réponse (ou même réponse 202 Accepted), meilleure isolation des pannes.

  2. Isoler le code de requête HTTP – Modulariser hookclient.php en classes : HttpClient, WebhookManager, RetryPolicy.

    • Gestion explicite des erreurs :
      « `php try {
      $client->post($url, $payload, $headers);
      } catch (HttpException $e) {
      $metrics->increment(‘webhook_failure’, [‘code’ => $e->getCode()]);
      $retry->schedule($e);
      }

    • Ajout d’un circuit‑breaker (ex. : Hystrix ou CircuitBreaker de Symfony).

  3. Mise en place d’une stratégie de retry/back‑off

    • 3 tentatives maximum.

    • Back‑off exponentiel (ex. : 1 s → 2 s → 4 s).

    • Enregistrement des payloads qui échouent systématiquement dans une dead‑letter queue (DLQ) pour investigation.

  4. Centraliser les logs

    • Structurer les logs au format JSON : timestamp, event_id, webhook_url, status, latency_ms, error_message.

    • Envoyer les logs à une solution agrégée (ELK, Loki, Graylog).

    • Créer des alertes sur les métriques critiques (taux d’échec > 2 %, latence > 3 s).

Étape 2 – Scaling de l’infrastructure

Dimension Action concrète Détails d’implémentation
Conteneurisation Déployer Dolibarr avec Docker Compose ou Kubernetes – Services : php-fpm, nginx, rabbitmq, redis, pgsql.
– Autoscalling du worker dédié aux webhooks (ex. : php-worker + horizontal pod autoscaler basé sur la longueur de la queue).
Worker dédié Créer un service “Webhook Processor” (micro‑service) uniquement responsable du traitement des webhooks – Code partagé via composer (autoload).
– Exécuté via php -S ou php-fpm en mode daemon.
– Possibilité de replicaSet (3 → 5 pods) en fonction de la charge.
Cache HTTP (optionnel) Mettre en cache les réponses GET vers les services externes (ex. : paiement) – HTTP‑Cache (Cache-Control) ou Varnish devant le worker.
Limitation & throttling Limiter le taux d’appels externes (ex. : 100 req/s) – Utiliser rate‑limiter (Redis‑Limiter) ou nginx limit_req.
Sécurité réseau Isoler les micro‑services dans un VPC ou Overlay network – Permettre uniquement le trafic vers les services de paiement ou de notification autorisés.

Étape 3 – Tests & Validation

  1. Tests unitaires & d’intégration – PHPUnit : couvrir HttpClient::post(), WebhookManager::dispatch().

    • Mock des services externes (via WireMock ou Mountebank).

  2. Stress‑testing

    • Locust / k6 : simuler 10 k webhook déclenchements simultanés.

    • Mesurer latence, taux d’erreur, saturation des workers.

  3. Chaos Engineering (optionnel)

    • Gremlin ou Chaos Mesh pour injecter des pannes réseau sur les destinations webhook et vérifier la robustesse du circuit‑breaker et de la DLQ.

  4. Mise en production contrôlée

    • Canary Deployment : déployer le nouveau worker sur 5 % du trafic pendant 48 h. – Monitorer les métriques et décider du scale‑out complet.

4. Checklist de passage à l’échelle (à valider avant “Go‑Live”)

✔️ Élément Vérification
1 Tous les webhooks ont un secret token et utilisent HTTPS Scan de sécurité, revue de code.
2 Le script de traitement est asynchrone (queue + worker) Monitoring du Worker, absence de timeout > 5 s.
3 Le rate‑limiter est activé et les quotas sont définis par URL Tests de dépassement de quota.
4 Les logs sont structurés et envoyés dans le système d’observabilité Recherche d’un champ event_id dans Grafana.
5 Les alertes sont actives (p.ex. : latence > 3 s, taux d’erreur > 2 %) Test en charge simulée.
6 Une DLQ est configurée pour les payloads qui échouent après N tentatives Validation d’un payload dans la file morte.
7 Le module de monitoring expose un tableau de bord « Webhooks » Dashboard Grafana partagé avec l’équipe Ops.
8 Le plan de rollback (revert du worker, ré‑activations du HTTP sync) est documenté Test de rollback sur l’environnement de pré‑prod.
9 Les tests de performance donnent une marge de 2× la charge prévue Rapport k6/Locust.
10 La documentation utilisateur et opérateur est mise à jour Confluence / Wiki interne.

5. Conclusions & perspectives

  • En diagnostic, la plupart des blocages surviennent à cause d’un modèle synchrone qui lie la charge des webhooks au temps de réponse d’une page web Dolibarr.

  • La solution consiste à déplacer le traitement vers une file d’attente et à exécuter les appels HTTP dans un worker dédié, ce qui libère la couche frontale et rend le système résilient aux pics de trafic.

  • La mise en place d’un monitoring complet, d’une gestion des erreurs robuste (retry + circuit‑breaker) et d’une architecture conteneurisée assure que Dolibarr pourra supporter plusieurs dizaines de milliers de webhooks sans perte de SLA.

Prochaine étape : lancer l’audit technique sur votre environnement de production actuel, prioriser les webhooks critiques (paiement, facturation, notifications temps réel) et planifier le sprint 0 de refactorisation du code hookclient.php.

Annexes

1. Exemple de configuration nginx pour les webhooks externes

location /webhook/ {

    proxy_pass         http://webhook-worker:9000;

    proxy_set_header   Host $host;

    proxy_set_header   X-Real-IP $remote_addr;

    proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;

    proxy_http_version 1.1;

    proxy_read_timeout   30s;

}

2. Script CLI de listing des webhooks Dolibarr (PHP)

#!/usr/bin/env php

<?phprequire __DIR__.'/src/Cfg.php';

use Dolibarr\Hook;
$hookList = Hook::getListOfHooks();     // Retourne array [url, description, enabled?]

foreach ($hookList as $hook) {

    echo sprintf("%s\t%s\t%s\n", $hook['url'], $hook['enabled'] ? 'ENABLED' : 'DISABLED', $hook['description']);

}

3. Dashboard Grafana (template rapide)

  • Panels :

    • Rate of Webhooks (rate(webhook_requests_total[5m]))

    • Latency Distribution (histogram_quantile(0.95, sum(rate(webhook_latency_seconds_bucket[1m])) by (le))

    • Error Rate (sum(rate(webhook_errors_total[5m])) / sum(rate(webhook_requests_total[5m])))

    • Queue Length (queue_length{service="webhook_processor"})

Bon diagnostic, bon scaling ! 🚀

Fin de l’article.

Publications similaires