Rejouer un webhook Stripe en mode test dans une suite Playwright

Un tunnel de paiement WooCommerce connecté à Stripe repose sur un échange asynchrone : le client paie côté Stripe, puis Stripe notifie le site via un webhook, qui seul déclenche le passage de la commande en « Traitement en cours ». Tester ce parcours en cliquant manuellement une carte de test à chaque déploiement est fastidieux, et surtout ça ne teste pas la partie la plus fragile : la réception et le traitement du webhook lui-même.

Nous avons mis en place un scénario Playwright qui utilise la CLI Stripe pour déclencher un véritable événement de test, laisse le webhook arriver naturellement sur le site, puis vérifie que la commande WooCommerce change bien de statut. C’est plus représentatif qu’un simple appel HTTP simulé à la main, car on teste la vraie chaîne : signature, endpoint, traitement.

Le problème : simuler un appel HTTP ne suffit pas

La tentation initiale est d’appeler directement l’endpoint /wc-api/wc_stripe avec un corps JSON fabriqué à la main. Le problème, c’est que Stripe signe chaque webhook avec un en-tête Stripe-Signature calculé à partir d’un secret partagé, et que WooCommerce rejette toute requête dont la signature ne correspond pas. Fabriquer cette signature à la main duplique une logique déjà fournie par Stripe, avec le risque de la faire dériver de l’implémentation réelle.

La solution : la CLI Stripe en écoute et en déclenchement

La CLI officielle stripe listen transmet les événements réels du compte de test vers un endpoint local ou de préproduction, avec la vraie signature calculée. On la démarre avant la suite de tests :

stripe listen --forward-to https://recette.exemple.fr/wc-api/wc_stripe --events checkout.session.completed

Le scénario Playwright déclenche ensuite le paiement via l’interface normale du site, avec une carte de test Stripe standard (4242 4242 4242 4242), puis attend que le webhook, transmis en parallèle par la CLI, mette à jour la commande.

Écrire le scénario complet

import { test, expect } from '@playwright/test';

test('paiement Stripe déclenche le webhook et met à jour la commande', async ({ page }) => {
  await page.goto('/commande/');
  await page.fill('#billing_email', 'client-test@exemple.fr');
  await page.click('#stripe-card-element');
  await page.keyboard.type('4242424242424242');
  await page.keyboard.press('Tab');
  await page.keyboard.type('1230');
  await page.keyboard.press('Tab');
  await page.keyboard.type('424');
  await page.click('#place_order');

  await expect(page.locator('.woocommerce-order-received')).toBeVisible({ timeout: 20000 });

  const numeroCommande = await page.locator('.woocommerce-order-overview__order strong').innerText();
  // le webhook doit être arrivé pendant ce délai et avoir mis le statut à jour côté admin
});

La vérification finale se fait côté administration, en interrogeant directement la commande pour confirmer que son statut est passé à processing, preuve que le webhook a bien été reçu et traité, pas seulement que la page de confirmation s’est affichée.

Vérifier le statut réel de la commande, pas seulement l’écran

await page.goto(`/wp-admin/post.php?post=${idCommande}&action;=edit`);
await expect(page.locator('#order_status')).toHaveValue('wc-processing');

Cette double vérification est essentielle : une commande peut afficher une page de remerciement au client sans que le webhook ait réellement mis à jour la base, notamment si Stripe retente l’envoi plus tard suite à un délai réseau.

Rejouer un événement Stripe pour tester la robustesse aux doublons

Stripe peut renvoyer le même événement plusieurs fois en cas de doute sur la réception. On simule ce cas avec :

stripe trigger checkout.session.completed --add checkout_session:metadata.order_id=1234

puis on vérifie qu’un second envoi du même événement ne duplique pas la commande ni ne déclenche un second envoi d’e-mail de confirmation, en s’appuyant sur l’idempotence native de l’ID d’événement Stripe traité côté WooCommerce.

• Toujours utiliser des clés de test Stripe (sk_test_), jamais les clés de production, même en environnement de recette.
• Nettoyer la commande de test après chaque exécution pour ne pas polluer les rapports de ventes.
• Consigner l’ID de l’événement Stripe dans les logs pour pouvoir rejouer manuellement un cas en cas d’échec intermittent.

Pour aller plus loin

Ce test ne couvre pas la vérification de signature elle-même ni la protection contre les webhooks falsifiés, qui relève d’une problématique de sécurité distincte. Il couvre uniquement le comportement fonctionnel attendu : un paiement réussi doit, par la voie du webhook, faire progresser la commande. C’est un scénario qui a mis en évidence, sur un projet e-commerce, un défaut de configuration d’URL d’endpoint après une migration de nom de domaine, invisible dans les tests manuels puisque le paiement en carte de test passait quand même.