DevOps Dolibarr : webhooks Tutoriel pas à pas pour mieux piloter

1️⃣ Introduction : pourquoi les webhooks ?

Besoin Solution via Webhook Bénéfice clé
Déclencher une action dès qu’un événement survient (ex. création d’une facture) Un appel HTTP POST vers un endpoint externe Réactivité instantanée, aucune vérification périodique
Synchroniser plusieurs outils (ERP ↔ CRM ↔ BI) Chaque événement publie un payload JSON Cohérence des données entre systèmes
Réduire la charge serveur Pas de polling, seul l’événement déclenche le traitement Consommation CPU / bande passante moindre
Faciliter les intégrations DevOps Les pipelines CI/CD peuvent réagir à des changements business Livraison continue alignée sur la réalité métier

Pour Dolibarr, la plateforme ERP/CRM open‑source très populaire, les webhooks permettent d’émettre des notifications chaque fois qu’un événemment (création/modification/suppression) se produit : commande, facture, contact, stock, etc. Ces notifications peuvent être consommées par des scripts, des services externes ou des pipelines d’intégration continue (CI/CD) pour automatiser le déploiement, la sauvegarde, le reporting, ou même le déclenchement de tests automatisés.

2️⃣ Prérequis : préparer votre environnement

  1. Une instance Dolibarr fonctionnelle (version ≥ 20).

  2. Un serveur d’applications capable d’écouter les requêtes HTTP (ex. Nginx, Apache, ou le serveur intégré de PHP).

  3. Un point d’accès public (URL stable) avec certificat SSL valide – indispensable pour la sécurité OAuth et la conformité REST.

  4. Un outil de test HTTP (cURL, Postman, ou httpie).

  5. (Optionnel) Un gestionnaire de secrets (ex. 1Password, HashiCorp Vault, ou envsubst) pour ne jamais hard‑coder les clés.

NOTE DevOps : Dans un contexte CI/CD, créez un secret (ex. DOLIBARR_WEBHOOK_SECRET) dans vos variables d’environnement afin que le secret du webhook ne soit jamais exposé dans les dépôts.

3️⃣ Étape 1 – Créer le Endpoint Webhook dans Dolibarr

  1. Connectez‑vous à l’interface d’administration de Dolibarr (Administration → Webhooks).

  2. Cliquez sur « Ajouter un webhook ».

  3. Remplissez les champs :

Champ Exemple Description
Nom Webhook Facture Créée Identifiant lisible.
URL https://api.monentreprise.com/webhooks/dolibarr Destination de l’appel HTTP POST.
Événement(s) Commande created, Invoice created Sélectionnez les triggers qui vous intéressent.
Méthode HTTP POST Par défaut, Dolibarr envoie toujours en POST.
En‑tête Content-Type application/json Le payload est envoyé en JSON.
Secret a1b2c3d4e5f6g7h8i9j0 Clé partagée pour le HMAC d’authentification.
Actif / Inactif ✅ Actif Activez‐le une fois les tests concluants.

  1. Sauvegardez.

  2. Testez immédiatement via le bouton Test de l’interface (ou en invoquant manuellement l’URL avec un payload d’exemple).

Astuce DevOps : Si votre endpoint est encore local, exposez‑le rapidement avec ngrok http 8080 ou similaires afin de recevoir les appels de Dolibarr pendant le développement.

4️⃣ Étape 2 – Implémenter le Receiver (Webhook Handler)

4.1 Architecture conseillée

/ (root)                     ->  index.php (router)

│                            │

├─ /webhooks                    ->  /handlers/dolibarr.php

│   ├─ verify_signature()     ->  vérifie HMAC‑SHA256 du header

│   ├─ parse_json()           ->  {event, data}

│   └─ dispatch_event(event)  ->  call_service()

│

└─ /ci                          ->  pipelines CI (GitHub Actions, GitLab CI…)

4.2 Code PHP minimal (receiver officiel)

<?php

// src/handlers/dolibarr.php

require_once __DIR__.'/../bootstrap.php';   // autoload / config
$secret   = getenv('DOLIBARR_WEBHOOK_SECRET'); // récupérer le secret

$payload  = file_get_contents('php://input');

$signature= $_SERVER['HTTP_X_DOLIBARR_SIGNATURE'] ?? '';
// 1️⃣ Vérification du signature HMAC

if (!hash_equals($secret, substr($signature, -64))) {

    http_response_code(401);

    exit('Signature invalid');

}
// 2️⃣ Décodage du JSON

$data = json_decode($payload, true);

if (!is_array($data)) {

    http_response_code(400);

    exit('Invalid JSON');

}
// 3️⃣ Routage selon l'événement

switch ($data['event']) {

    case 'Invoice.created':

        handleInvoiceCreated($data['data']);

        break;

    case 'Order.created':

        handleOrderCreated($data['data']);

        break;

    default:

        // Ignorer ou logger

        error_log('Webhook non géré : '. $data['event']);

        break;

}
function handleInvoiceCreated(array $invoice): void {

    // Exemple : déclencher une sauvegarde automatisée

    exec('docker exec backup_container php /scripts/backup_facture.php '. $invoice['id']);

    // Ou publier sur un topic Kafka / SNS …

}
// Vous pouvez enrichir le service (bdd, messaging, etc.)

Points de sécurité essentiels

Risque Mitigation
Injection de code via $payload Décoder en json_decode uniquement, ne jamais eval.
Replay attack (réception d’un même webhook plusieurs fois) Conserver le timestamp (event_date) et le comparer à une fenêtre (ex. < 5 min).
Exposition de secrets Stocker le secret dans une variable d’environnement, jamais en clair dans le repo.
DDoS Rate‑limit au niveau du reverse‑proxy (ex. limit_req_zone Nginx) ou via un WAF.

5️⃣ Étape 3 – Intégrer le Webhook dans votre pipeline CI/CD

5.1 Exemple avec GitHub Actions

# .github/workflows/dolibarr.yml

name: Trigger on Dolibarr Webhook
on:

  workflow_dispatch:            # déclenchable manuellement

  schedule:

    - cron: '*/5 * * * *'       # vérif. toutes les 5 min (fallback)
jobs:

  react:

    runs-on: ubuntu-latest

    steps:

      - name: Checkout repo

        uses: actions/checkout@v4
- name: Pull latest changes

        run: git pull
- name: Build & Test

        run: |

          composer install --no-dev --prefer-dist

          vendor/bin/phpunit
- name: Deploy to staging

        env:

          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}

        run: |

          ./deploy.sh staging

Intégration du webhook
Lorsque Dolibarr envoie Invoice.created, le webhook receiver appelé précédemment peut déclencher un appel HTTP vers l’API GitHub pour créer un workflow dispatch :

function triggerGitHubWorkflow(int $runId, string $invoiceId): void {

    $payload = [

        'ref' => 'main',

        'inputs' => ['invoice_id' => $invoiceId]

    ];

    $ch = curl_init('https://api.github.com/repos/yourorg/yourrepo/dispatches');

    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));

    curl_setopt($ch, CURLOPT_HTTPHEADER, [

        'Accept: application/vnd.github+json',

        'Authorization: token '.$_SERVER['HTTP_X_GITHUB_TOKEN']

    ]);

    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    curl_exec($ch);

}

Ainsi, chaque création de facture entraîne automatiquement un build dédié, évitant les tests redondants.

5.2 Exemple avec GitLab CI (trigger par API)

curl -X POST "https://gitlab.com/api/v4/projects/<PROJECT_ID>/trigger/pipeline" \

  -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \

  -d "ref=main&variables=INVOICE_ID=$invoiceId"

Intégrez ce même appel dans le handleInvoiceCreated() du Webhook Handler.

6️⃣ Étape 4 – Tester & Valider l’Intégration

Action Méthode
Émettre un événement test Dans l’admin Dolibarr, créez manuellement une Facture ou une Commande.
Capturer le payload Utilisez curl -v http://votre-webhook.local/webhooks/dolibarr pour voir les headers et le corps.
Vérifier la signature Comparez le X-Dolibarr-Signature avec le HMAC calculé côté serveur (hash_hmac('sha256', $payload, $secret)).
Observer la chaîne CI Dans GitHub Actions ou GitLab, assurez‑vous que le workflow démarre et se termine avec succès.
Analyser les logs Ajoutez du error_log() ou Monolog pour tracer chaque étape (received, verified, processed, error).
Cleanup Bloquez le webhook temporaire (/tmp/webhook_test) une fois les tests terminés.

7️⃣ Bonnes pratiques DevOps pour les Webhooks Dolibarr

Domaine Recommandation
Sécurité – Utilisez toujours un secret partagé.
– Limitez les CORS à vos domaines de confiance.
– Restreignez l’accès par IP si possible (ex. allow 203.0.113.12).
Scalabilité – Découplez le receiver en micro‑service (Docker/K8s) et exposez‑le via un Ingress avec autoscaling.
– Utilisez un message broker (Kafka, RabbitMQ) pour découpler le traitement asynchrone.
Observabilité – Centralisez les logs (ELK, Loki).
– Exportez des métriques (webhook_requests_total, webhook_failures_total) via Prometheus.
– Créez des alertes sur les taux d’erreur > 5 %.
Gestion du versioning – Versionnez l’URL du webhook (/v1/webhooks/...) pour éviter les ruptures lors d’évolution du schéma.
Rollback – En cas de changement de payload inattendu, gardez la capacité de désactiver le webhook sans impacter la prod.
Documentation vivante – Documentez chaque webhook (nom, événements, payload JSON, secret) dans un registre partagé (ex. docs/webhooks.md dans le repo Git).

8️⃣ Exemple complet : Workflow « Création Facture → Backup automatisé »

  1. Création de la facture dans l’interface Dolibarr.

  2. Dolibarr envoie un webhook Invoice.created à https://api.monentreprise.com/webhooks/dolibarr.

  3. Receiver (dolibarr.php) vérifie le HMAC (X-Dolibarr-Signature).

  4. Le payload est décodé, la fonction handleInvoiceCreated() est déclenchée.

  5. handleInvoiceCreated() lance le script backup_facture.php dans un conteneur Docker (ou appelle un job GitHub Actions).

  6. Le script dépose la facture dans le bucket S3 ou sauvegarde la base de données.

  7. Le job CI/CD démarre (si vous avez opté pour un trigger GitHub) pour bâtir les tests spécifiques aux faits de facturation.

  8. Toutes les actions sont loggées et métriques envoyées à Prometheus.

  9. En cas d’échec, une alerte Slack est envoyée, le webhook est désactivé automatiquement via l’API de Dolibarr.

Resultat : Aucun script manuel n’est plus nécessaire, la chaîne de bout en bout est déclarative, versionnée et observable.

9️⃣ Checklist de déploiement (à cocher avant go‑live)

  • [ ] Le secret du webhook est stocké dans les variables d’environnement.

  • [ ] Le endpoint utilise HTTPS avec certificat valide.

  • [ ] La signature HMAC est vérifiée à chaque appel.

  • [ ] Les payloads sont validés (schema JSON via ajv ou équivalent).

  • [ ] Le processus de traitement ne dépasse pas le timeout du reverse‑proxy (ex. 30 s).

  • [ ] Les métriques (taux de succès, latence) sont exposées sur /metrics.

  • [ ] Les logs sont redirigés vers un système centralisé (ex. Loki).

  • [ ] Un plan de rollback (désactivation du webhook via API) est documenté.

  • [ ] Les secrets Docker/K8s sont synchronisés avec le Vault ou Secrets Manager.

10️⃣ Conclusion

Les webhooks Dolibarr constituent un levier puissant pour orchestrer les processus DevOps autour d’un ERP. En suivant ces étapes — création de l’endpoint, développement d’un receiver sécurisé, intégration dans votre chaîne CI/CD, puis mise en place de bonnes pratiques d’observabilité et de sécurité — vous transformez de simples notifications métier en véritables déclencheurs d’automatisation.

À retenir :

  1. Sécurisez chaque appel (secret + HMAC).

  2. Découpez le traitement (receiver → service → pipeline).

  3. Versionnez vos webhooks pour éviter les ruptures inattendues.

  4. Surveillez en continu grâce à des métriques et logs centralisés.

Vous avez maintenant tout le nécessaire pour piloter vos flux Dolibarr depuis votre stack DevOps, réduire les tâches manuelles et garantir que chaque changement métier est immédiatement et fiablement propagé à travers votre écosystème technique.

Bonne automatisation ! 🚀

Publications similaires