Webhooks DataFirefly — Guide complet

Présentation

Webhooks DataFirefly relie votre boutique PrestaShop 8 et 9 à plus de 5000 applications, dans les deux sens. En sortant, votre boutique émet ses événements (commandes, clients, stock…) vers Zapier, Make, n8n ou n’importe quel endpoint HTTP. En entrant, ces mêmes outils peuvent pousser des données dans la boutique via une API sécurisée.

Le module repose sur trois piliers : une file d’attente asynchrone (aucune commande ralentie), des relances automatiques à backoff exponentiel, et une signature HMAC-SHA256 pour garantir l’authenticité des messages.

Installation

1. Téléchargez l’archive dfwebhooks.zip depuis votre compte DataFirefly.
2. Dans le back-office, allez dans Modules > Module Manager > Téléverser un module et déposez le ZIP.
3. Cliquez sur Installer, puis sur Configurer.
4. Vous arrivez sur l’écran principal qui affiche l’URL du worker cron et l’URL de l’API entrante.

1. Planifier le worker cron (flux sortant)

Les webhooks sortants ne sont pas envoyés immédiatement : ils sont mis en file puis livrés par un worker que vous déclenchez périodiquement. Copiez l’URL du cron affichée sur l’écran de configuration et planifiez-la toutes les 1 à 5 minutes.

*/2 * * * * curl -s "https://votre-boutique.com/index.php?fc=module&module=dfwebhooks&controller=cron&token=VOTRE_TOKEN" >/dev/null 2>&1

À chaque passage, le worker traite jusqu’à 50 livraisons en attente, applique les relances nécessaires et purge les anciens journaux selon la durée de rétention configurée.

2. Créer un endpoint sortant

Un endpoint relie un événement à une URL de destination. Depuis l’écran principal, cliquez sur Ajouter, puis renseignez :

• Nom : un libellé interne (ex. « Nouvelle commande → Zapier »).
• Événement : l’événement déclencheur (voir la liste plus bas).
• URL : collez l’URL « Catch Hook » de Zapier ou « Custom Webhook » de Make.
• Secret de signature (optionnel) : si renseigné, chaque payload est signé en HMAC-SHA256.

Filtres conditionnels

Vous pouvez n’envoyer un webhook que lorsque certaines conditions sont remplies. Les règles sont au format JSON et combinées en ET logique. Opérateurs disponibles : eq, neq, gt, gte, lt, lte, in, contains.

[{"field":"order.total_paid","op":"gte","value":100}]

Cet exemple ne déclenche le webhook que pour les commandes dont le total payé est supérieur ou égal à 100.

Mapping de champs

Par défaut, le payload complet est envoyé. Pour n’envoyer que certains champs sous un format précis, définissez un mapping : la clé est le nom de sortie, la valeur le chemin dans le payload.

{"email":"customer.email","total":"order.total_paid"}

3. Événements sortants disponibles

• order.created — une commande vient d’être validée.
• order.status.updated — le statut d’une commande change.
• order.refunded — une commande passe au statut remboursé.
• customer.created — un nouveau client s’inscrit.
• address.created — une nouvelle adresse est créée.
• product.created — un produit est ajouté.
• product.updated — un produit est modifié.
• product.stock.low — le stock passe sous le seuil configuré.
• review.created — un avis est validé (nécessite un module d’avis compatible).

4. API entrante (Zapier/Make/n8n → PrestaShop)

L’API entrante permet à vos automatisations de modifier la boutique. Elle est protégée par un token et, optionnellement, par une signature HMAC.

Créer un token

Dans le panneau Tokens entrants, donnez un libellé, choisissez les scopes autorisés (orders, products, customers) et, si vous le souhaitez, un secret de signature. Le token généré est à coller dans votre outil.

Envoyer une requête

Effectuez un POST sur l’URL de l’API entrante. Le token passe dans l’en-tête X-DF-Token (ou en paramètre ?token=). Le corps est un JSON avec une action et un objet data.

POST https://votre-boutique.com/index.php?fc=module&module=dfwebhooks&controller=api
X-DF-Token: VOTRE_TOKEN
Content-Type: application/json

{"action":"order.status.update","data":{"id_order":42,"id_order_state":4}}

5. Actions entrantes disponibles

• order.status.update (scope orders) — change le statut d’une commande. Champs : id_order, id_order_state, send_email (optionnel).
• order.get (scope orders) — récupère une commande. Champ : id_order.
• product.stock.update (scope products) — fixe le stock. Champs : id_product, quantity, id_product_attribute (optionnel).
• product.upsert (scope products) — crée ou met à jour un produit par sa reference.
• customer.upsert (scope customers) — crée ou met à jour un client par son email.
• customer.get (scope customers) — récupère un client par email ou id_customer.

6. Vérifier la signature HMAC

Si un secret est configuré sur l’endpoint (sortant) ou le token (entrant), le message porte un en-tête X-DF-Signature: sha256=.... Pour la vérifier côté réception, recalculez le HMAC du corps brut avec votre secret et comparez en temps constant.

$expected = "sha256=" . hash_hmac("sha256", $rawBody, $secret);
if (hash_equals($expected, $signatureHeader)) {
    // signature valide
}

Comparez toujours le HMAC calculé sur le corps brut (non re-sérialisé), sinon la signature ne correspondra pas.

7. Journal de livraison et rejeu

Le menu Webhooks Delivery Log liste chaque tentative avec son statut :

• SENT — livré avec un code HTTP 2xx.
• PENDING — en file, en attente du prochain passage du worker.
• FAILED — échec temporaire, une relance est planifiée.
• DEAD — échec définitif après 6 tentatives.

Les relances suivent un backoff exponentiel : 1 minute, 5 minutes, 30 minutes, 2 heures, puis 6 heures. Vous pouvez forcer un nouvel envoi à tout moment via le bouton Replay, et inspecter le payload exact depuis l’action Voir.

8. Multiboutique, RGPD et mode batch

Chaque endpoint et chaque token sont rattachés à une boutique précise : les flux d’une boutique ne fuitent jamais vers une autre. L’option Anonymiser les données personnelles masque e-mails, téléphones et noms avant l’envoi, pour rester conforme au RGPD lorsque la destination ne doit pas recevoir de données nominatives. Le mode batch regroupe les envois pour les gros volumes.

FAQ et dépannage

Aucun webhook n’est envoyé. Vérifiez que le worker cron est bien planifié et que son URL (avec le bon token) répond. Consultez le journal : si les lignes restent en PENDING, c’est que le cron ne tourne pas.

L’endpoint distant renvoie une erreur 401/403. Votre outil attend peut-être une vérification de signature : renseignez le même secret des deux côtés, ou retirez-le pendant les tests.

L’API entrante renvoie « insufficient_scope ». Le token utilisé n’a pas le scope requis par l’action. Modifiez le token pour cocher le scope correspondant (orders, products ou customers).

La page de test affiche un échec. Le bouton Test envoie un payload d’exemple en synchrone : un échec indique généralement une URL injoignable ou un certificat TLS invalide côté destination.