Webhooks Shopify : tutoriel complet pour automatiser ton business

Un webhook Shopify, c'est simple : plutôt que d'aller demander à Shopify toutes les 5 minutes "est-ce qu'il s'est passé quelque chose ?", tu lui dis "préviens-moi quand ça arrive". Ta commande est passée, ton stock change, un client crée un compte : Shopify envoie une requête HTTP POST à ton URL, en temps réel, avec toutes les données. Pas de polling, pas de délai artificiel, pas de ressources gaspillées.

Le problème, c'est que la plupart des boutiques Shopify n'exploitent pas ça. Soit parce que le concept paraît technique, soit parce que la doc officielle ne dit pas vraiment quoi en faire concrètement. Ce tutoriel, c'est l'inverse : du concret, des cas d'usage qui tournent, et les pièges à éviter avant qu'ils te coûtent du chiffre.

Qu'est-ce qu'un webhook Shopify et pourquoi tu en as besoin

Webhooks vs API : quelle différence concrète pour ton e-commerce

L'API Shopify, tu l'interroges. Tu envoies une requête GET, tu reçois une réponse. C'est toi qui prends l'initiative. C'est utile pour récupérer des données à la demande, mais dès que tu veux réagir à un événement en temps réel, le polling devient un cauchemar : coûteux en requêtes API, soumis aux rate limits (40 requêtes/seconde sur le plan standard), et forcément en décalage.

Un webhook Shopify, c'est l'inverse. C'est Shopify qui t'appelle. Dès qu'un événement se produit sur ta boutique, Shopify envoie une requête POST vers l'URL que tu as configurée, avec le payload JSON complet de l'événement. Tu n'as pas à demander, tu n'attends pas, tu ne pollues pas ton quota API.

La différence en pratique :

• Avec le polling : tu vérifies toutes les 5 minutes si une commande est passée. Si une commande arrive entre deux vérifications, tu réagis avec du retard.
• Avec un webhook orders/create : la notification arrive en moins d'une seconde après la validation du paiement.

Pour un business e-commerce sérieux, les webhooks ne sont pas une option. Dès que tu intègres un ERP, un CRM, un outil d'email marketing, ou un WMS externe, travailler sans webhooks, c'est bricoler.

Les cas d'usage qui paient vraiment (synchro stock, CRM, email marketing)

Oublie les exemples théoriques. Voici ce que des boutiques réelles font avec les webhooks Shopify :

• Synchro stock en temps réel : chaque vente déclenche une mise à jour dans ton ERP ou ton WMS. Plus de désynchronisation, plus de survente sur des produits épuisés.
• Alimentation CRM : à chaque nouvelle commande ou nouveau client, les données partent automatiquement dans HubSpot, Klaviyo, ou tout autre CRM. Zéro saisie manuelle.
• Triggers d'email marketing : un orders/fulfilled déclenche un email de tracking. Un refunds/create déclenche un email de remboursement personnalisé. Tes séquences post-achat deviennent automatiques.
• Notifications internes : chaque commande supérieure à 500€ envoie une alerte Slack à ton équipe. Aucun outil tiers ne fait ça aussi proprement que ton propre webhook.
• Fraude et risque : un orders/create avec des données suspectes déclenche une vérification automatique avant expédition.

Ce sont des gains opérationnels directs. Pas de la théorie.

Les événements Shopify les plus utiles à monitorer

Orders, Products, Customers : par où commencer

Shopify expose des dizaines de topics webhook. En pratique, 80% des besoins e-commerce tiennent dans une douzaine d'événements. Voici les plus utiles par catégorie :

Topic webhook	Quand il se déclenche	Cas d'usage principal
orders/create	Nouvelle commande validée	Alimentation CRM, notification interne, anti-fraude
orders/updated	Modification d'une commande existante	Synchro ERP, mise à jour statut client
orders/cancelled	Commande annulée	Remise en stock, trigger email annulation
orders/fulfilled	Commande expédiée	Email tracking automatique, mise à jour CRM
products/create	Nouveau produit créé	Synchro catalogue externe, PIM
products/update	Produit modifié	Mise à jour catalogue, alerte équipe
customers/create	Nouveau compte client	Opt-in email marketing, segmentation CRM
customers/update	Profil client modifié	Mise à jour liste email, CRM sync
inventory_levels/update	Stock modifié	Alerte rupture, synchro entrepôt

Si tu démarres, commence par orders/create et customers/create. Ce sont les deux événements qui ont le plus d'impact immédiat sur tes processus business.

Fulfillment et Refunds : ce qu'il faut vraiment tracker

Ces deux catégories sont souvent sous-utilisées alors qu'elles représentent des moments critiques dans l'expérience client.

Le topic fulfillments/create se déclenche quand un fulfillment est créé pour une commande, c'est-à-dire quand elle commence à être préparée. C'est différent de orders/fulfilled qui confirme l'expédition complète. Si tu travailles avec un 3PL ou un entrepôt externe, monitorer ce topic te permet de savoir exactement où en est chaque commande à chaque étape.

Pour les remboursements, refunds/create est indispensable. Il te permet :

• De déclencher automatiquement un email de confirmation de remboursement
• De mettre à jour ton CRM avec l'historique de remboursement du client
• D'alimenter ton outil de comptabilité (Pennylane, QuickBooks...) en temps réel
• De remettre en stock les articles retournés si tu gères tes retours manuellement

Configuration des webhooks : la marche à suivre

Via l'admin Shopify (la façon simple)

Si tu n'as pas besoin de créer des dizaines de webhooks et que tu veux quelque chose de fonctionnel en 5 minutes, l'interface admin suffit largement.

1. Connecte-toi à ton admin Shopify
2. Va dans Paramètres > Notifications
3. Descends jusqu'à la section "Webhooks" tout en bas
4. Clique sur "Créer un webhook"
5. Sélectionne l'événement dans la liste déroulante (ex: Commande créée)
6. Renseigne l'URL de ton endpoint (ex: https://ton-serveur.com/webhooks/orders)
7. Choisis le format (JSON recommandé)
8. Sélectionne la version d'API
9. Clique sur "Enregistrer"

Shopify affiche alors ton secret de webhook. Copie-le immédiatement : tu ne pourras plus le voir après. C'est ce secret qui te permet de vérifier la signature de chaque requête entrante.

Via l'API (pour les intégrations avancées)

Dès que tu dois créer plusieurs webhooks, les gérer programmatiquement, ou les intégrer dans une app Shopify, passe par l'API. Deux options : REST ou GraphQL.

Via l'API REST, une requête POST suffit :

POST /admin/api/2024-10/webhooks.json
Content-Type: application/json
X-Shopify-Access-Token: {ton_token}

{
  "webhook": {
    "topic": "orders/create",
    "address": "https://ton-serveur.com/webhooks/orders",
    "format": "json"
  }
}

Via l'API GraphQL, tu utilises la mutation webhookSubscriptionCreate. C'est plus verbeux mais plus flexible, notamment pour les webhooks sur des topics plus récents qui ne sont disponibles qu'en GraphQL.

Pour lister tes webhooks existants et vérifier qu'ils sont actifs :

GET /admin/api/2024-10/webhooks.json

La réponse te donne l'ID, le topic, l'adresse, la version d'API, et la date de création de chaque webhook. Garde cette liste à jour : Shopify désactive automatiquement les webhooks dont l'endpoint retourne des erreurs répétées.

Déboguer tes webhooks et éviter les pièges courants

Vérifier la signature webhook (sécurité non-négociable)

Ton endpoint webhook est une URL publique. N'importe qui peut lui envoyer une requête POST. Si tu ne vérifies pas que la requête vient vraiment de Shopify, tu exposes ton système à des injections de fausses données.

Shopify signe chaque requête avec un header X-Shopify-Hmac-Sha256. C'est un hash HMAC-SHA256 du body brut de la requête, calculé avec ton secret webhook. La vérification côté serveur est simple :

# Python
import hmac
import hashlib
import base64

def verify_webhook(data, hmac_header, secret):
    computed = hmac.new(
        secret.encode('utf-8'),
        data,
        hashlib.sha256
    ).digest()
    computed_b64 = base64.b64encode(computed).decode('utf-8')
    return hmac.compare_digest(computed_b64, hmac_header)

Quelques points critiques :

• Utilise le body brut (raw bytes), pas le JSON parsé. Si tu parses avant de vérifier, la signature ne matchera pas.
• Utilise hmac.compare_digest ou équivalent, jamais une comparaison directe de strings (timing attack).
• Si la signature ne correspond pas, retourne immédiatement un HTTP 401 et logge l'incident.

Gérer les retries et les timeouts

Shopify attend une réponse HTTP 2xx en moins de 5 secondes. Si ton endpoint ne répond pas dans ce délai, ou retourne une erreur (4xx, 5xx), Shopify va réessayer. Le schéma de retry suit une progression exponentielle sur 48 heures, avec 19 tentatives maximum.

Le piège classique : faire du traitement lourd directement dans le handler webhook. Si tu dois envoyer des données à une API externe, mettre à jour une base de données, ou déclencher des emails, ne fais pas ça de façon synchrone.

La bonne architecture :

1. Le handler webhook reçoit la requête, vérifie la signature
2. Il place le payload dans une queue (Redis, SQS, RabbitMQ...)
3. Il retourne immédiatement HTTP 200
4. Un worker asynchrone traite le payload depuis la queue

Cette approche découple la réception du traitement et évite les timeouts même si l'API externe que tu appelles est lente ou down.

Logs et monitoring : tes meilleurs alliés

Sans logs, tu travailles à l'aveugle. Chaque requête webhook entrant doit être loggée avec au minimum :

• L'horodatage exact
• Le topic de l'événement
• L'ID de la ressource concernée (order ID, customer ID...)
• Le statut de traitement (reçu, traité, erreur)
• Le code HTTP retourné

L'admin Shopify affiche les 5 dernières tentatives de livraison pour chaque webhook, avec le statut HTTP de la réponse. C'est le premier endroit où regarder si quelque chose ne fonctionne pas. Accessible dans Paramètres > Notifications, section Webhooks.

Pour aller plus loin, branche un outil comme Datadog, Better Uptime, ou même un simple Sentry pour capturer les exceptions dans ton handler. Un webhook qui échoue silencieusement, c'est une synchro CRM qui accumule du retard ou un stock qui dérive.

Intégrations concrètes : 3 exemples qui marchent

Synchro automatique avec ton système d'inventaire

C'est le cas d'usage numéro un pour les boutiques qui ont un entrepôt physique ou travaillent avec un 3PL.

Le flow :

1. Client passe commande sur Shopify
2. orders/create déclenche ton webhook
3. Ton handler extrait les line items (produits, quantités, variants)
4. Il appelle l'API de ton WMS pour créer un ordre de préparation
5. Le WMS confirme la création, tu mets à jour un champ personnalisé sur la commande Shopify via l'API

En parallèle, si ton WMS gère les niveaux de stock, un webhook inventory_levels/update côté Shopify te prévient dès qu'un niveau change, pour synchroniser dans l'autre sens si nécessaire.

Pour les boutiques avec plusieurs entrepôts, Shopify Locations te permet de monitorer chaque location séparément. Le payload inventory_levels/update inclut le location_id : tu sais exactement quel entrepôt est concerné.

Envoi de données commandes vers ton CRM ou email platform

Deuxième cas d'usage qui génère un ROI immédiat : alimenter ton CRM ou ta plateforme d'email marketing (Klaviyo, Brevo, ActiveCampaign...) en temps réel.

Sur orders/create, le payload Shopify contient tout ce dont tu as besoin : informations client, produits achetés, montant total, code promo utilisé, source de trafic si tu l'as taggée. En une requête vers l'API de ton CRM, tu peux :

• Créer ou mettre à jour le contact client avec ses dernières infos
• Enregistrer la commande comme une activité sur le profil
• Segmenter automatiquement (premier achat, VIP, acheteur d'une catégorie spécifique)
• Déclencher une séquence email post-achat (suivi, cross-sell, demande d'avis)

Sur customers/create, tu peux déclencher une séquence de bienvenue différente selon que le client vient de créer un compte sans acheter (nurturing) ou dans le cadre d'une première commande (onboarding acheteur).

Pour les boutiques qui cherchent à automatiser à grande échelle, ce type d'intégration webhook constitue souvent la colonne vertébrale du système : c'est ce qui permet de faire tourner un business à 6 ou 7 chiffres sans empiler les équipes opérationnelles.

Outils et services pour fiabiliser tes webhooks

Tu n'as pas besoin de tout construire from scratch. L'écosystème autour des webhooks est mature et plusieurs outils te font gagner des semaines de développement.

Outil	Usage principal	Quand l'utiliser
ngrok	Tunnel local pour tester	Dev et debugging sans déployer
Webhook.site	Inspection de payloads en temps réel	Comprendre ce que Shopify envoie exactement
Svix	Infrastructure webhook clé en main	Si tu envoies toi-même des webhooks à tes clients
Hookdeck	Queue, retry, monitoring de webhooks entrants	Fiabiliser la réception sans code custom
Make (ex-Integromat)	Automation no-code avec webhooks	Intégrations simples sans développeur
Zapier	Automation no-code populaire	Connexions rapides entre apps, limité en logique complexe
Sentry	Monitoring d'erreurs applicatives	Capturer les exceptions dans tes handlers

Hookdeck mérite une mention spéciale. C'est une infrastructure dédiée aux webhooks entrants qui te donne, sans écrire une ligne de code infra : une queue persistante, du retry automatique, un dashboard de monitoring, et la possibilité de rejouer des événements passés. Si tu construis une intégration critique, c'est 50 à 80 heures de dev évitées.

Pour les intégrations no-code, Make est généralement plus puissant que Zapier pour les logiques conditionnelles complexes. Mais ni l'un ni l'autre ne remplace une architecture propre dès que tu as des volumes importants ou des règles métier non-triviales.

Erreurs qui coûtent cher et comment les éviter

Ces erreurs, on les voit régulièrement. Elles ne sont pas catastrophiques immédiatement, mais elles créent des dettes techniques et des problèmes opérationnels qui s'accumulent.

1. Ne pas vérifier la signature HMAC

C'est l'erreur numéro un. Un endpoint ouvert sans vérification de signature, c'est une surface d'attaque. Quelqu'un peut forger une requête qui simule une commande, un remboursement, ou une mise à jour de stock. Conséquences potentielles : données CRM corrompues, stock faussé, emails déclenchés à tort. La vérification prend 10 lignes de code. Pas de raison de l'omettre.

2. Traitement synchrone dans le handler

Appeler une API externe directement dans le handler, sans queue asynchrone. Si l'API externe est lente (2-3 secondes), tu dépasses le timeout Shopify de 5 secondes. Shopify retry, ton endpoint traite deux fois la même commande, et tu te retrouves avec des doublons. Architecture queue + worker : obligatoire dès que tu fais autre chose qu'une réponse instantanée.

3. Ignorer l'idempotence

Shopify peut livrer le même événement plusieurs fois. Sans système de déduplication (stockage de l'ID webhook déjà traité), tu risques d'envoyer deux emails de confirmation pour la même commande, de décrementer deux fois le stock, ou de créer deux leads dans ton CRM. Stocke les IDs dans Redis ou ta base de données et vérifie à chaque traitement.

4. Utiliser une version d'API non spécifiée

Si tu crées tes webhooks sans spécifier de version d'API, Shopify utilise la version par défaut de ta boutique. Quand Shopify déprécie une version, tes webhooks peuvent casser du jour au lendemain. Spécifie toujours une version explicite (ex: 2024-10) et planifie tes migrations vers les nouvelles versions.

5. Aucun alerting sur les échecs

Shopify désactive un webhook après 19 échecs consécutifs. Si tu n'as pas d'alerting, tu peux passer 48 heures sans le savoir, pendant lesquelles ta synchro CRM est morte, ton stock dérive, et tes emails de suivi ne partent plus. Mets en place au minimum une alerte email ou Slack quand un webhook est désactivé par Shopify.

Un webhook cassé silencieusement, c'est pire qu'une panne visible. La panne visible, tu la traites. Le webhook mort que personne n'a monitoré, tu le découvres quand le dommage est déjà fait.

6. Confondre orders/paid et orders/create

Une commande peut être créée sans être payée (paiement différé, chèque, COD). Si tu déclenches tes processus logistiques sur orders/create sans vérifier le statut financier, tu peux préparer des commandes qui ne seront jamais payées. Pour les triggers qui doivent attendre la confirmation de paiement, utilise orders/paid ou vérifie financial_status === "paid" dans le payload.

Foire aux questions

Questions fréquentes

Comment configurer un webhook Shopify étape par étape sans galère ?

Via l'admin Shopify : Paramètres > Notifications > Webhooks > Créer un webhook. Tu choisis l'événement, tu renseignes l'URL de ton endpoint, tu sélectionnes le format JSON et la version d'API. Shopify te donne un secret à copier immédiatement. Pour tester localement avant de déployer, utilise ngrok pour exposer ton serveur local. Pour créer des webhooks en masse ou dans une app, utilise l'API REST ou GraphQL avec une requête POST sur le endpoint /admin/api/2024-10/webhooks.json.

Quel événement webhook dois-je suivre pour mon type de business ?

Si tu as un entrepôt ou un 3PL, commence par orders/create et inventory_levels/update. Si tu priorises l'email marketing et le CRM, commence par orders/create et customers/create. Si tu gères beaucoup de retours, ajoute refunds/create et orders/cancelled. La règle pratique : identifie les processus que tu fais manuellement aujourd'hui et trouve le topic webhook qui correspond à chaque déclencheur.

Comment vérifier que mes webhooks fonctionnent réellement ?

Deux méthodes. La première : dans l'admin Shopify (Paramètres > Notifications > Webhooks), tu peux envoyer un webhook de test pour chaque configuration. La réponse HTTP s'affiche immédiatement. La deuxième : Webhook.site te donne une URL publique temporaire qui capture et affiche toutes les requêtes entrantes en temps réel. Configure un webhook Shopify vers cette URL pour voir exactement le payload que Shopify envoie, avant même d'avoir un endpoint opérationnel.

Que faire si un webhook ne se déclenche pas ou se déclenche mal ?

Commence par vérifier dans l'admin Shopify l'historique des tentatives de livraison (Paramètres > Notifications > Webhooks). Si Shopify indique des erreurs HTTP (4xx ou 5xx), le problème est côté ton endpoint. Si Shopify indique "succès" mais que tu ne reçois rien, vérifie tes logs serveur et ta chaîne de traitement asynchrone. Si le webhook n'apparaît pas du tout dans l'historique, vérifie que le topic correspond bien à l'événement qui s'est produit et que le webhook est actif (non désactivé par Shopify suite à des échecs répétés).

Comment sécuriser mes webhooks et vérifier que les données viennent vraiment de Shopify ?

Vérifie le header X-Shopify-Hmac-Sha256 sur chaque requête entrante. Ce header contient un hash HMAC-SHA256 du body brut de la requête, calculé avec ton secret webhook. Tu recalcules ce hash côté serveur avec le secret que Shopify t'a donné à la création du webhook, et tu compares les deux. Si ça ne matche pas, tu rejettes la requête avec un HTTP 401. Utilise une comparaison de strings en temps constant (hmac.compare_digest en Python, crypto.timingSafeEqual en Node.js) pour éviter les timing attacks.

Shopify peut-il désactiver mes webhooks automatiquement ?

Oui. Après 19 tentatives de livraison consécutives en échec (HTTP non-2xx ou timeout), Shopify désactive le webhook automatiquement. Tu reçois un email de notification si une adresse email est configurée sur ton compte. La réactivation est manuelle : soit depuis l'admin, soit via une requête PUT sur l'API. Pour éviter ça, mets en place un monitoring de ton endpoint avec un outil comme Better Uptime ou UptimeRobot, et configure des alertes dès qu'il renvoie des erreurs.

Ce que tu dois faire maintenant

Les webhooks Shopify ne sont pas complexes. Ce qui est complexe, c'est de les intégrer proprement dans une architecture qui tient la route à l'échelle : queue asynchrone, idempotence, monitoring, gestion des versions d'API. C'est là que la plupart des boutiques se retrouvent avec une dette technique qui freine leur croissance.

Si tu pars de zéro : commence par orders/create, vérifie la signature, mets une queue, monitore. Tu auras 80% des bénéfices avec 20% de l'effort.

Si tu as déjà des webhooks en prod et que tu n'es pas sûr de leur fiabilité, ou si tu hésites encore sur la bonne stratégie d'intégration pour ton stack technique, une session de diagnostic change la donne. On regarde ce qui existe, on identifie les risques, on priorise.

Si tes webhooks te pourrissent la scalabilité ou que tu sais même pas par où commencer, réserve une session d'audit avec Peii : on te dit exactement quoi mettre en place et comment.