Testez les webhooks WooCommerce sur Localhost

Pour tester les webhooks WooCommerce sur localhost, exposez votre gestionnaire local avec un tunnel HTTPS, créez un webhook sous WooCommerce → Paramètres → Avancé → Webhooks et vérifiez X-WC-Webhook-Signature en tant que résumé Base64 HMAC-SHA256 du corps brut. Déclenchez une commande ou un changement de produit dans un magasin de test sécurisé, inspectez la livraison et itérez sans déployer le récepteur.

Ce que WooCommerce envoie et quand

WooCommerce peut notifier une URL de livraison lorsque des commandes, des produits, des coupons ou des clients sont créés, mis à jour ou supprimés. Les extensions peuvent ajouter des sujets et les développeurs peuvent définir des sujets personnalisés. Chaque webhook configuré a un nom, un statut, un sujet, une URL de livraison, un secret et une version de l'API. Le documentation officielle du webhook WooCommerce décrit la création, les sujets, les journaux de livraison et le comportement en cas d'échec.

Un webhook est attaché automatiquement à un sujet, et non à chaque mutation de magasin. Choisissez le sujet le plus restreint dont votre intégration a besoin. Un consommateur créé par une commande ne doit pas également traiter chaque mise à jour du produit. Cela réduit l’exposition des données personnelles, le trafic et les effets secondaires accidentels lors des tests locaux.

Créer un point de terminaison Express de corps brut

La signature de WooCommerce est calculée sur le corps qu'il envoie. Conservez ces octets jusqu'à ce que la vérification soit terminée. L’en-tête de signature contient le résumé binaire HMAC-SHA256 codé en base64, et non une chaîne hexadécimale.

import express from 'express';
import crypto from 'node:crypto';

const app = express();

function validWooSignature(rawBody, supplied, secret) {
  if (!supplied || !secret) return false;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('base64');
  const a = Buffer.from(supplied);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post(
  '/webhooks/woocommerce',
  express.raw({ type: 'application/json', limit: '2mb' }),
  async (req, res) => {
    const supplied = req.get('x-wc-webhook-signature');
    if (!validWooSignature(req.body, supplied, process.env.WC_WEBHOOK_SECRET)) {
      return res.sendStatus(401);
    }

    const payload = JSON.parse(req.body.toString('utf8'));
    await webhookInbox.insertOnce({
      deliveryId: req.get('x-wc-webhook-delivery-id'),
      topic: req.get('x-wc-webhook-topic'),
      payload,
    });
    return res.sendStatus(202);
  },
);

app.use(express.json());
app.listen(3000);

L'analyseur brut spécifique à l'itinéraire doit être exécuté avant un analyseur JSON global. Si le middleware analyse d'abord le corps, la re-stringification de l'objet peut modifier les espaces ou s'échapper et invalider le résumé. Il s'agit de la même règle du corps brut abordée dans le guide de signature de webhooks, mais WooCommerce utilise spécifiquement la sortie Base64.

Démarrer le tunnel HTTPS

1. Démarrez votre récepteur et confirmez qu'il écoute http://localhost:3000.
2. Courir npx portpreview 3000 dans un deuxième terminal.
3. Copiez l'URL HTTPS publique et ajoutez-la /webhooks/woocommerce.
4. Maintenez le processus en cours pendant que WordPress envoie ses premières livraisons de ping et de sujets.

L'hébergeur WordPress (et non le navigateur sur lequel vous avez ouvert wp-admin) doit pouvoir accéder à l'URL publique. Un tunnel relie cette demande publique à votre processus de développement privé. Il fournit également un TLS de confiance, vous n'avez donc pas besoin d'exposer un port de routeur ou d'installer votre propre certificat public.

Configurer le webhook dans WooCommerce

1. Ouvrir WooCommerce → Paramètres → Avancé → Webhooks.
2. Sélectionner Ajouter un webhook et donnez-lui un nom de développement local reconnaissable.
3. Choisir Actif statut et un sujet spécifique, tel que Commande créée.
4. Collez l’URL complète de livraison du tunnel.
5. Générez un long secret aléatoire et placez la valeur identique dans WC_WEBHOOK_SECRET.
6. Enregistrez le webhook, puis déclenchez le sujet dans un magasin de test.

Lorsqu'un webhook actif est enregistré pour la première fois, WooCommerce envoie un ping à l'URL de livraison. Le ping confirme la connectivité mais ne remplace pas une charge utile de commande réelle. Faites en sorte que votre point de terminaison tolère la requête initiale, puis créez ou mettez à jour les données de test pour tester le sujet sélectionné.

export WC_WEBHOOK_SECRET="$(openssl rand -base64 48)"

Si vous collez un secret Base64 dans un fichier d'environnement, citez-le afin que la ponctuation soit préservée. Le secret est la clé HMAC ; Les clés client de l’API REST WooCommerce et les mots de passe WordPress ne sont pas des informations d’identification indépendantes.

Utiliser des en-têtes pour acheminer et tracer les livraisons

WooCommerce inclut des en-têtes de métadonnées utiles. Selon la version et l'environnement, ceux-ci incluent le sujet, la ressource, l'événement, la source, l'ID du webhook et l'ID de diffusion. Traitez les noms sans tenir compte de la casse, comme l'exige HTTP. Utilisez le sujet pour l'expédition et l'ID de livraison pour la traçabilité, mais authentifiez toujours le corps en premier.

const handlers = {
  'order.created': handleOrderCreated,
  'order.updated': handleOrderUpdated,
  'product.updated': handleProductUpdated,
};

const handler = handlers[topic];
if (handler) await handler(payload);
else await recordUnsupportedTopic(topic);

Ne déduisez pas le sujet uniquement à partir de la forme JSON. Une charge utile de commande créée et mise à jour de commande peut se ressembler, tandis que l'action correcte en aval diffère. À l’inverse, rejetez une combinaison en-tête/sujet pour laquelle votre point de terminaison n’a jamais été configuré.

Traiter les charges utiles des commandes de manière défensive

Utiliser des identifiants immuables

Corrélez les enregistrements par identité de magasin et ID d'objet WooCommerce, et non par formatage du numéro de commande, e-mail du client ou noms d'affichage. Deux magasins peuvent tous deux avoir l'ID de commande 42, les intégrations multi-magasins nécessitent donc une clé composée.

Attendez-vous à ce que les extensions modifient les champs

Les extensions de paiement, d'abonnement, de taxe, de paiement et de traitement des commandes peuvent ajouter des métadonnées et des champs d'éléments de ligne. Validez les champs requis par votre logique métier, ignorez les champs inconnus et enregistrez une version de schéma ou un montage minimal rédigé pour les tests de régression.

Séparer la réception de l'événement de l'exécution

Un webhook indiquant qu'une commande a été modifiée doit entrer dans une file d'attente ou une boîte de réception durable. La synchronisation des stocks, les étiquettes d'expédition, les appels ERP et les e-mails des clients doivent être exécutés après accusé de réception. Cela évite qu’une dépendance lente oblige WooCommerce à interpréter une réception réussie comme un échec de livraison.

Mises à jour du modèle lors des transitions d'état

Une commande peut passer par les états en attente, en traitement, en attente, terminée, annulée, remboursée ou en échec. Les mises à jour peuvent être effectuées rapidement et le bon de livraison ne constitue pas un substitut sûr à la comparaison des horodatages et de l'état actuel de la source. Rendre les transitions répétées inoffensives.

L'idempotence est obligatoire pour les événements commerciaux

Un délai d'attente peut survenir après la validation de votre récepteur, mais avant que WooCommerce ne voie la réponse. La relivraison produit alors la même action commerciale, sauf si le gestionnaire est idempotent. Conservez l’identifiant de livraison s’il est présent. Appliquez également l’unicité au niveau du domaine, comme une demande d’exécution par magasin et une transition de commande.

await db.transaction(async (tx) => {
  if (!(await tx.deliveries.claim(deliveryId))) return;
  await tx.orders.applyWooCommerceEvent(storeId, topic, payload);
  await tx.outbox.enqueueRequiredActions(storeId, topic, payload.id);
});

Une transaction boîte de réception et boîte d'envoi évite à la fois la gestion en double et la perte de travail de suivi. Voir nouvelle tentative de webhook et idempotence pour le modèle complet.

Utilisez les journaux WooCommerce pour déboguer le côté expéditeur

WooCommerce enregistre les livraisons de webhooks. Ouvrir WooCommerce → Statut → Journaux et filtrez la source de livraison du webhook décrite dans la documentation officielle. Comparez l'URL de livraison, l'heure de la demande, l'état de la réponse et le corps de la réponse avec votre trace de tunnel local. Les journaux de l'expéditeur indiquent si WordPress a tenté la demande ; les journaux du récepteur répondent à ce que votre application en a fait.

Ne copiez pas une charge utile de commande non expurgée dans un problème public. Il peut contenir des noms, des adresses de facturation et de livraison, des e-mails, des numéros de téléphone, des sélections de produits et des métadonnées de paiement. Réduisez le luminaire aux champs requis pour reproduire le bug.

Résoudre les échecs courants du webhook WooCommerce

Le webhook devient désactivé

WooCommerce désactive automatiquement un webhook après plus de cinq échecs de livraison consécutifs. Les réponses en dehors de 2xx, 301 ou 302 comptent comme des échecs selon le guide officiel. Corrigez le point de terminaison, réactivez le webhook et envoyez un test contrôlé. Évitez de toute façon les redirections : elles compliquent le débogage des signatures et peuvent accidentellement envoyer des données client signées à un hôte involontaire.

La signature diffère toujours

Hachez le corps brut exact avec le secret configuré du webhook, demandez la sortie binaire HMAC, puis encodez-le en Base64. Dans Node, c'est .digest('base64'). Les erreurs courantes consistent à utiliser l'hexadécimal, à utiliser un secret de l'API REST, à analyser d'abord JSON ou à inclure des octets de nouvelle ligne supplémentaires.

Le ping initial fonctionne mais pas les événements de commande

Confirmez que le sujet sélectionné correspond à l'action que vous avez déclenchée. Créer une commande et modifier une commande existante sont des sujets différents. Vérifiez que l'état est Actif, vérifiez les journaux WooCommerce et assurez-vous qu'un plugin ou un cache intermédiaire n'empêche pas le hook sous-jacent.

Les requêtes locales renvoient 404

Vérifiez le chemin complet, la méthode de routage et le port cible du tunnel. WordPress doit POSTER sur /webhooks/woocommerce, pas seulement l'origine du tunnel. Le middleware du framework ne doit pas rediriger le webhook vers une page localisée ou authentifiée.

Délai de livraison écoulé

Conservez l’événement authentifié et renvoyez 200 ou 202 rapidement. Déplacez les appels d'API à distance et les transformations lourdes vers un travailleur. Vérifiez si les points d'arrêt locaux suspendent la demande suffisamment longtemps pour être classés comme un échec.

La relecture d'une charge utile provoque un 401

Une demande capturée doit conserver les octets bruts exacts et l’en-tête de signature. La modification de JSON invalide la signature originale. Pour les tests de logique métier, utilisez un appareil nettoyé après la limite de vérification ; pour les tests de bout en bout, générez un nouveau HMAC avec un secret de test dédié. Suivez le flux de travail de relecture sécurisé.

Liste de contrôle de sécurité pour les données du magasin local

• Testez sur un magasin intermédiaire avec des clients et des produits synthétiques autant que possible.
• Utilisez un secret de webhook unique pour le développement local et faites-le pivoter après exposition.
• Vérifiez la signature avant d'analyser, de journaliser ou de mettre le corps en file d'attente.
• Ajoutez la source et le sujet du magasin attendus après la vérification cryptographique.
• Rédigez les adresses, les coordonnées, les notes de commande et les métadonnées de paiement des captures.
• Ne désactivez jamais la vérification TLS et n’exposez jamais les informations d’identification wp-admin au destinataire.

L'architecture locale doit correspondre à la production : transport HTTPS, authentification du corps brut, acceptation durable, traitement idempotent, réponse rapide et échecs vérifiables. Pour un autre fournisseur de commerce avec un en-tête HMAC différent, comparez le Guide des webhooks locaux Shopify.