Webhooks et tâches planifiées

Webhooks

Accès : Banque > Mollie > Webhooks (administrateurs uniquement)

Les webhooks sont des notifications automatiques envoyées par Mollie à votre serveur Dolibarr lorsqu'un événement se produit (paiement reçu, remboursement traité, contestation ouverte, etc.).

Configuration du webhook

L'URL du webhook est automatiquement gérée par le module. Elle suit le format :

https://votre-dolibarr.example.com/custom/mollie/public/hook.php

Cette URL est communiquée à Mollie lors de la création de chaque paiement. Mollie envoie ensuite les notifications à cette adresse.

Important : L'URL du webhook doit être accessible depuis Internet (pas de localhost). En mode test, vous pouvez utiliser un outil comme ngrok pour exposer votre serveur local.

Types d'événements gérés

Le module traite automatiquement les notifications pour :

Préfixe ID	Type d'événement	Action
`tr_`	Paiement	Mise à jour du statut, synchronisation des remboursements et contestations
`re_`	Remboursement	Synchronisation des remboursements du paiement associé
`sub_`	Abonnement	Mise à jour du statut de l'abonnement
`chb_`	Contestation	Synchronisation des contestations du paiement associé
`stl_`	Règlement	Création ou mise à jour du règlement
`pl_`	Lien de paiement	Mise à jour du statut du lien de paiement

Journal des webhooks

La page Webhooks affiche l'historique de toutes les notifications reçues :

ID Mollie de l'objet concerné
Type d'événement (payment, refund, subscription, chargeback, settlement, payment_link)
Statut du traitement :
- Reçu - Notification reçue, en cours de traitement
- Traité - Notification traitée avec succès
- Échoué - Erreur lors du traitement
- Ignoré - Notification ignorée (type inconnu)
Code HTTP retourné (200 = succès, 400 = notification invalide, 500 = échec temporaire)
Temps de traitement en millisecondes
Date de réception

Journal des webhooks avec les types d'événements, codes HTTP et temps de traitement

Fiche d'un webhook

La fiche détaillée affiche :

Informations générales (ID, type, statut, code HTTP)
Temps de traitement
Dates de réception et de traitement
Message d'erreur (en rouge si le traitement a échoué)
Contenu brut (payload JSON) de la notification, affiché de manière formatée

Le journal des webhooks est un outil de diagnostic. Il permet de vérifier que les notifications Mollie sont correctement reçues et traitées. En cas de problème, consultez le message d'erreur dans la fiche du webhook.

Que se passe-t-il en cas d'échec

Mollie renvoie une notification pendant 26 heures tant que la réponse n'est pas un succès. Le module s'appuie sur ce comportement :

Échec temporaire (base occupée, paramètre non encore renseigné, création de facture en erreur) : le module répond 500. Mollie redélivrera la notification et le paiement finira par être enregistré.
Échec définitif (paiement dans une autre devise que l'objet, montant différent de celui annoncé, objet introuvable) : le module répond 200 pour ne pas réessayer en boucle, et la notification reste au statut Échoué pour examen manuel.

Dans les deux cas, la ligne du journal conserve le message d'erreur.

Si l'utilisateur pour les actions n'est pas renseigné dans la configuration, toutes les notifications de paiement échouent avec un code 500. Renseignez-le : les notifications seront redélivrées par Mollie, et la tâche planifiée rejoue de son côté les webhooks restés en échec.

Tâches planifiées

Le module définit trois tâches planifiées (cron jobs) pour la synchronisation automatique. Elles sont désactivées par défaut et doivent être activées manuellement depuis Accueil > Configuration > Tâches planifiées.

MollieCheckPay

Vérification des paiements et reversements

Fréquence : Quotidienne
Action : Vérifie les statuts des paiements en cours auprès de l'API Mollie et synchronise les reversements
Utilité : Filet de sécurité pour rattraper les webhooks manqués

MollieCheckTakePayments

Lancement automatique des paiements

Fréquence : Quotidienne
Action : Recherche les factures impayées dont le mode de paiement est CB ou prélèvement SEPA (associé au compte bancaire Mollie) et lance automatiquement les prélèvements
Utilité : Automatisation complète du recouvrement

Une facture n'est retenue que si le client dispose d'un mandat valide enregistré dans le module (mandat directdebit pour un prélèvement SEPA, creditcard pour une carte), tel qu'il apparaît dans Banque > Mollie > Mandats SEPA.

Les mandats signés depuis la page publique sont donc bien pris en compte. Si un client n'est jamais prélevé, vérifiez d'abord qu'il apparaît dans la liste des mandats avec le statut Valide et la bonne méthode.

Cette tâche ne fonctionne qu'en mode production : en mode test, elle s'arrête immédiatement avec un message dans les logs.

MollieCheckInvoicesPaid

Mise à jour des factures payées

Fréquence : Quotidienne
Action : Vérifie les factures Dolibarr rattachées au compte bancaire Mollie et les passe en "Payée" lorsqu'il ne reste plus rien à payer, avoirs et acomptes compris
Utilité : Synchronisation du statut entre Mollie et Dolibarr

Cette tâche ne touche que les factures dont le compte bancaire est le compte Mollie : clôturer une facture encaissée par un autre canal n'est pas de son ressort.

Planification

Les tâches sont programmées à une heure aléatoire entre minuit et 6h du matin pour éviter de surcharger l'API Mollie si plusieurs installations Dolibarr exécutent les tâches simultanément.

Conseil : Il est recommandé d'activer au minimum la tâche MollieCheckPay comme filet de sécurité, même si les webhooks fonctionnent correctement.