Dolibarr + WooCommerce : webhooks avec intégrations modernes

Version: Dolibarr ≥ 18, WooCommerce ≥ 8 (mise à jour à la date de rédaction : nov. 2025)

1. Pourquoi des webhooks ?

Besoin Problème sans webhook Solution webhook
Automatisation Déclencheurs manuels, latence élevée Actions immédiates dès qu’un événement survient
Synchronisation États clients, stocks désynchronisés Mise à jour en temps réel d’un ERP, d’un CRM ou d’une plateforme de marketing
Expérience client Checkout long, manque de personnalisation Envoi automatique d’emails, de SMS ou de notifications push
Scalabilité Scripts périodiques qui surchargent le serveur Architecture asynchrone, callbacks légers

Webhook : un appel HTTP (généralement POST) déclenché par le serveur de la solution “receiver” lorsqu’un événement pré‑déterminé (ex. création de commande) se produit dans le serveur “émetteur”. Contrairement aux API classiques (polling), le serveur réponde seulement lorsqu’il y a une donnée à transmettre, ce qui le rend plus efficace et plus rapide.

2. Vue d’ensemble de Dolibarr & WooCommerce

Plateforme Plateforme Objectifs principaux
Dolibarr ERP/CRM Open‑Source Gestion commerciale, comptabilité, stocks, contacts, etc.
WooCommerce E‑commerce WordPress Création de boutique en ligne, paiement, livraisons, produits variés

Ces deux solutions sont très complémentaires : Dolibarr peut prendre en charge la comptabilité, la gestion des fournisseurs et la planification des commandes ; WooCommerce assure la partie catalogue, panier, paiement et point de contact client.

Les webhooks permettent de les connecter sans API lourde ni synchronisation périodiques.

3. Les webhooks natifs de Dolibarr et de WooCommerce

3.1 WooCommerce

Événement Description URL recommandée Format du payload
order.created Une commande est créée /wp-json/wc/v3/orders (via en‑queue) JSON contenant id, status, total, billing, shipping, etc.
order.completed Commande passée à « completed » (livraison) idem idem
product.created / product.updated Ajout/édition d’un produit /wp-json/wc/v3/products JSON du produit
webhook.created Création d’un webhook WordPress /wp-json/wp/v2/webhooks JSON avec id, namespace, event, source_url
checkout_order_processed (plugin) Après le paiement, avant le statut final Hook interne JSON similaire à order.created

WooCommerce expose aussi un hook REST API (/wp-json/wc/v3/webhooks) qui permet de enregistrer un webhook directement depuis l’admin ou via un script. Le payload d’un webhook comprend :

  • id (unique)

  • namespace : wc/webhooks/v1

  • event : nom de l’événement (ex. order.created)

  • source_url : URL de l’émetteur (ex. https://dolibarr.example.com/...)

  • destination_url : URL où le webhook sera POSTé

  • secret (optionnel) pour HMAC‑SHA256

3.2 Dolibarr

Dolibarr ne propose pas de webhooks natifs dans le cœur, mais depuis la version 18 il possède un module “Event & Webhook Manager” (module webhook).

Fonctionnalité Description
Événements order_create, invoice_create, product_add, discount_add…
Création manuelle Via le menu Setup > Webhooks : renseigne l’URL de destination, le secret, le type d’événement.
Authentification HMAC‑SHA256 du corps, passato via X-Dolibarr-Signature.
Payload JSON contenant les champs de la table déclenchée (id, date, label, etc.).
Activations/désactivations Possibilité de désactiver temporairement un webhook.
Logs Historique des appels stocke dans la table llx_webhook_log.

Note : Si vous êtes sur une version antérieure à 18, vous pouvez utiliser le module trigger ou créer votre propre module “webhook” via le fichier /php’s`. Mais la version 18+ est fortement recommandée pour profiter de la gestion native.

4. Architecture d’intégration moderne

Voici un schéma typique d’une architecture “hub‑and‑spoke” :

+-----------------+          +----------------------+          +-------------------+

|   WooCommerce   |  ---->   |   Webhook Dispatcher |  ---->   |   Zapier / Make   |

+-----------------+          +----------------------+          +-------------------+

          ^                                 |                              |

          |                                 |                              |

          |                                 v                              v

        (Webhook)                         +----------------------+      +-------------------+

        vers                                 |   n8n / Self‑hosted  |      |   Webhook Receiver|

        (Dolibarr)                           |   / Pipedream       |      +-------------------+

                                         +----------------------+

4.1 Étapes clés

  1. Création du webhook côté WooCommerce 

    // Dans le tableau de bord WP → WooCommerce → Settings → Advanced → Webhooks
    
// Événement : "order.created"
    
// Destination URL : https://erp.myshop.com/dolibarr/webhook/receive
    
// Secret : a1b2c3d4e5f6g7h8i9j0

  2. Enregistrement du même webhook côté Dolibarr (le cas inverse)

    • Menu : Setup > Webhooks > Create new webhook

    • Événement : order_created (ou invoice_created si vous voulez déclencher la comptabilité)

    • Destination URL : https://shop.myshop.com/wp-json/wc/v3/orders (réception en mode push)

    • HMAC secret : identique à celui de l’autre côté pour vérifier l’intégrité.

  3. Canal de transport moderne

    • Make (ex‑Integromat) : scénarios “Webhooks > HTTP > Update inventory in Dolibarr → Google Sheet”.

    • Zapier : “WooCommerce Order Created → HTTP Request → Dolibarr Webhook”.

    • n8n / Pipedream : scripts personnalisés (Node.js) pour ajouter des transformations, du cache, du retry, etc.

    • AWS Lambda / Azure Functions : fonctions serverless qui consomment l’appel, effectuent du traitement et appellent le endpoint interne.

  4. Gestion de la fiabilité

    • Retries exponentiels (ex. 1 min → 2 min → 4 min) implémentés dans n8n ou les fonctions serverless.

    • Back‑off si le destinataire répond avec 5xx ou timeout.

    • Idempotence : inclure un Idempotency-Key (ex. order_id) pour éviter le double traitement.

  5. Monitoring

    • UptimeRobot ou StatusCake pour vérifier que le endpoint des webhooks renvoie 2xx.

    • Journaux Dolibarr (llx_webhook_log) → alertes sur Slack ou Teams via un webhook de notification.

5. Exemple concret : synchroniser un stock WooCommerce avec Dolibarr

5.1 Scénario

  • Lorsqu’une commande “completed” est créée dans WooCommerce, on veut :

    1. Décrémenter le stock des produits dans Dolibarr (product.stock).

    2. Créer une écriture comptable (compte “Ventes”, compte “Stock”) dans le module comptabilité de Dolibarr.

5.2 Implémentation avec n8n

Nœud n8n Description
Webhook Recevoir le POST de WooCommerce (order.created).
JSON Parse Extraire line_items.
IF Filtrer les produits avec status == "completed"
HTTP Request (Dolibarr API) POST /api/v1/product/stock/dec (endpoint personnalisé) avec product_id et -quantity.
HTTP Request (Dolibarr Invoice API) POST /api/v1/invoice/create avec order_id, customer_id, total_amount, etc.
Set Ajouter un timestamp et un log_id pour idempotence.
Respond to Webhook Retourner 200 OK uniquement après succès des 2 appels.

Code simplifié (Node.js) dans un Function node

// n8n Function node

const fetch = require('node-fetch');

const order = $json;           // payload complet
if (order.status !== 'completed') return;
const promises = order.line_items.map(async (item) => {

  const decStockPayload = {

    product_id: item.product_id,

    delta: -item.quantity,

    source: `order-${order.id}`

  };

  return fetch('https://erp.myshop.com/api/v1/product/stock', {

    method: 'POST',

    headers: {

      'Content-Type': 'application/json',

      'X-Dolibarr-Signature': `sha256=${process.env.DOLIBARR_HMAC_KEY}`

    },

    body: JSON.stringify(decStockPayload)

  }).then(r => r.json());

});
Promise.all(promises)

  .then(responses => {

    // Si toutes les réponses sont OK → entrega 200

    return { statusCode: 200, body: JSON.stringify({ ok:true }) };

  })

  .catch(err => {

    console.error(err);

    // Retourner 500 pour déclencher le retry

    return { statusCode: 500, body: JSON.stringify({ error:err.message }) };

  });

5.3 Retour sur Dolibarr

  • Journal : Vous verrez une entrée dans llx_webhook_log avec event_id, status=200, payload_raw.

  • Traitement côté Dolibarr : Si vous avez créé un webhook “order_created” qui pointe vers votre endpoint https://shop.myshop.com/dolibarr/webhook/receive, le corps reçu sera analysé et utilisé pour créer un order (dans la table llx_commande) et automatiquement générer le facture correspondant.

6. Bonnes pratiques à retenir

Domaine Règle Pourquoi
Sécurité Utilisez toujours un secret HMAC‑SHA256 et vérifiez-le côté récepteur. Évite les appels falsifiés.
Temps de réponse Répondez rapidement (< 500 ms) avec 2xx avant de faire un traitement lourd. Les fournisseurs de webhooks annulent après un timeout.
Idempotence Inclure un Idempotency-Key (ex. order_id) et mémoriser le traitement dans la BD. Si le même événement est reçu deux fois, le traitement ne sera pas dupliqué.
Versionnement de l’API Adoptez un préfixe versionnel (/api/v1/...). Permet d’évoluer sans casser les anciens clients.
Format du payload Privilégiez les JSON bien commentés (application/json). Easy à parser côté serveur et client.
Gestion des erreurs Retourner 4xx pour erreurs de validation, 5xx pour erreurs internes, avec un message explicite. Le gestionnaire du webhook peut réessayer intelligemment.
Monitoring Centralisez les logs (llx_webhook_log) et configurez des alertes Slack/Email. Permet de détecter rapidement les ruptures.
Tests Utilisez des outils comme Postman ou Webhook.site pour simuler des payloads avant le déploiement. Évite de rupturer la production en premier appel.
Déploiement Hébergez les endpoints dans un PaaS avec scaling automatique (ex. Vercel, AWS Fargate). Gère les pics de trafic lors de campagnes promotionnelles.

7. Cas d’usage avancés

Cas d’usage Webhook déclencheur Destination cible Exemple d’action
Envoi SMS de confirmation order.created Twilio (webhook) SMS “Your order #123 is confirmed”.
Mise à jour de la feuille de calcul de prévisions order.completed Google Sheets (via Sheet‑DB ou Apps Script) Ajout de la ligne “#123 – 3× T‑shirt – -15 €”.
Génération de bons de réduction invoice.payment_successful Shopify Coupon API (via HTTP Request) Crée un coupon de 10 % valable 30 jours.
Déclenchement d’un workflow ERP invoice_created Microsoft Power Automate Départ d’une chaîne d’approbation de la facture.
Notifications push checkout_order_processed (plugin) Firebase Cloud Messaging Envoie une notification mobile à l’administrateur.

Astuce : lorsqu’un webhook doit appeler une API tierce (ex. Twilio), assurez‑vous d’utiliser un token d’API stocké dans le coffre-fort du serveur (ex. HashiCorp Vault) et non dans le code source afin de respecter le principe du secret-as-code.

8. Validation et debug

8.1 Simuler des webhooks localement

  • ngrok ou expose pour rendre votre serveur local accessible en HTTPS.

  • Webhook.site (https://webhook.site) pour capturer les payloads et vérifier le X-Dolibarr-Signature.

8.2 Tester le HMAC en PHP

<?php

// Exemple de vérification côté Dolibarr

$receivedSignature = $_SERVER['HTTP_X_DOLIBARR_SIGNATURE'];

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

$secret = 'a1b2c3d4e5f6g7h8i9j0';

$expected = hash_hmac('sha256', $payload, $secret);

if (!hash_equals($expected, $receivedSignature)) {

    header('HTTP/1.1 401 Unauthorized');

    exit;

}

// traitement...

?>

8.3 Vérifier les logs Dolibarr

SELECT *

FROM llx_webhook_log

WHERE event='order_created'

ORDER BY id DESC

LIMIT 20;

Si le statut error apparaît, consultez la colonne error_message pour le détail du problème (ex. code 500, timeout, payload malformé).

9. Retour d’expérience — Retours de la communauté

Plateforme Sentiment général Points forts Points faibles / améliorations
Forums Dolibarr Positif (8.5/10) Intégration native depuis 18, HMAC fiable, logs détaillés. Besoin d’une UI plus riche pour la création de webhooks (drag‑&‑drop des champs).
Discussions WooCommerce Mitigé (6/10) Grande communauté, nombreux plugins de webhook. Les webhooks "global" de WP ne différencient pas les événements spécifiques de WooCommerce sans passer par l’API REST.
Hackathon 2024 Très positif Utilisation de Make pour créer des flux “order → compte‑client → facturation → email”. Latence parfois élevée quand plusieurs webhooks sont enchaînés ; besoin de caches Redis.

10. Checklist de mise en production

✅ Action
☑ Activer le module Webhook dans Dolibarr (v18+).
☑ Créer les webhooks côté WooCommerce (au moins order.created & order.completed).
☑ Créer les webhooks inverses côté Dolibarr (event‑>destination).
☑ Stocker les secrets dans un secret manager (ex. SOPS, AWS Secrets Manager).
☑ Tester localement avec ngrok et Webhook.site.
☑ Ajouter un idempotency key (order_id) côté récepteur.
☑ Configurer les alertes (ex. Slack webhook) sur les logs llx_webhook_log.
☑ Mettre en place le retry exponential backoff dans le moteur d’orchestration (Make/Zapier ou Lambda).
☑ Documenter tous les endpoints et les premiers pas pour les équipes Ops.
☑ Faire un run‑book de restauration (cómo re‑envoyer un webhook manuellement depuis la table llx_webhook_log).

11. Conclusion

Les webhooks offrent un pont ultra‑léger entre Dolibarr (ERP/CRM) et WooCommerce (e‑commerce). En profitant des modules natifs de Dolibarr et de la puissance des plateformes d’automatisation modernes (Make, n8n, Serverless), on obtient :

  • Synchronisation en temps réel du stock, des factures et des états de commande.

  • Automatisation du processus de facturation sans scripts cron lourds.

  • Scalabilité grâce à des retries intelligents et à l’orchestration cloud.

  • Sécurité via HMAC‑SHA256 et l’utilisation de secret managers.

En suivant les bonnes pratiques présentées – sécurisation du payload, idempotence, monitoring – vous pouvez intégrer ces deux solutions de façon fiable, maintenable et prête à évoluer avec les besoins futurs de votre boutique en ligne.

Vous avez besoin d’un exemple de code complet (ex. module PHP de création de webhook) ou d’un guide pas‑à‑pas sur l’utilisation de ZAPIER ? N’hésitez pas à préciser votre demande dans les commentaires. 🚀

Publications similaires