Webhooks Stripe et Lemon Squeezy idempotents dans Next.js

Vérifiez la charge utile brute avant de toucher au JSON

Chaque prestataire de paiement signe la séquence exacte d'octets envoyée sur le réseau. Si un gestionnaire de route analyse await request.json() puis resérialise l'objet avant de vérifier la signature, les différences d'ordre des clés ou d'espaces invalideront des webhooks légitimes — ou inciteront les développeurs à désactiver la vérification en préproduction.

Lisez le corps brut une seule fois avec await request.text() dans votre gestionnaire POST Next.js App Router, vérifiez la signature cryptographique avec le secret serveur et rejetez tout échec avec un code HTTP 400 avant d'exécuter la moindre requête SQL. Le guide du module de facturation montre comment supastack isole la vérification des signatures derrière un point d'entrée BFF unique.

export async function POST(request: Request) {
  const rawBody = await request.text();
  const signature = request.headers.get("stripe-signature");
  if (!signature) return new Response("Missing signature", { status: 400 });

  const event = stripe.webhooks.constructEvent(
    rawBody,
    signature,
    env.STRIPE_WEBHOOK_SECRET,
  );
  await handleNormalizedBillingEvent(event);
  return Response.json({ received: true });
}

• Lisez le corps brut de la requête avec request.text() — ne resérialisez jamais du JSON déjà analysé.
• Conservez STRIPE_WEBHOOK_SECRET et les secrets de signature Lemon Squeezy dans une configuration strictement côté serveur.
• Utilisez une comparaison à temps constant (crypto.timingSafeEqual) lors de la vérification manuelle de signatures HMAC.

Dédupliquez à la frontière de la base de données, pas en mémoire

Stripe et Lemon Squeezy renvoient les webhooks dès qu'un déploiement redémarre, qu'une fonction serverless expire ou qu'un saut réseau perd la réponse. Les ensembles en mémoire ou les clés de cache éphémères disparaissent entre les instances et n'empêcheront pas deux tentatives simultanées d'accorder deux licences ou d'envoyer deux reçus par e-mail.

Enregistrez l'identifiant d'événement du prestataire ou l'état de règlement de la commande dans la même transaction Postgres que celle qui modifie les droits d'abonnement. Un INSERT ... ON CONFLICT DO NOTHING atomique ou une mise à jour conditionnelle sur status != 'paid' transforme un rejeu simultané en opération neutre. Pour concevoir les offres que ces webhooks activent, le générateur de page de tarifs SaaS aide à modéliser les paliers et les sièges en amont.

const settled = await db.transaction(async (tx) => {
  const [inserted] = await tx
    .insert(billingWebhookEvents)
    .values({ providerEventId: event.id, provider: "stripe" })
    .onConflictDoNothing({ target: billingWebhookEvents.providerEventId })
    .returning({ id: billingWebhookEvents.id });

  if (!inserted) return false; // Already processed
  await applyWorkspaceEntitlement(tx, event);
  return true;
});

• SaaS Pricing Page Generator (Free Tool)supastack.dev

Gérez les événements désordonnés et les abonnements qui se chevauchent

Rien ne garantit que les webhooks arrivent dans l'ordre où l'utilisateur a cliqué. customer.subscription.updated peut arriver avant checkout.session.completed, et un client qui ouvre accidentellement deux onglets de paiement peut détenir brièvement deux abonnements dans le même workspace.

Rattachez les résiliations et les échecs de paiement à l'identifiant d'abonnement précis qui a déclenché l'événement. Avant de révoquer le droit payant d'un workspace, vérifiez si un autre abonnement actif couvre toujours ce workspace — sinon la résiliation d'un doublon supprime silencieusement l'accès que le client continue de payer.

• Indexez l'état de l'abonnement par providerSubscriptionId, et pas uniquement par workspaceId.
• Maintenez le droit payant d'un workspace actif tant qu'au moins un abonnement est active ou trialing.
• Vérifiez que le montant payé et la devise correspondent au SKU attendu avant d'honorer les commandes à paiement unique.

Questions fréquentes sur les webhooks de facturation SaaS

Ces questions reviennent chaque fois qu'une équipe passe la facturation des tests sandbox au trafic de production.

• Puis-je débloquer les fonctionnalités payantes dès la redirection de succès du paiement ? — Non. Les URL de redirection peuvent être mises en favoris, partagées ou visitées avant le règlement des moyens de paiement asynchrones. Utilisez la page de succès pour interroger l'état du serveur pendant que le webhook vérifié accorde l'accès.
• Quel code HTTP doit renvoyer un webhook en doublon ? — Renvoyez 200 OK dès que votre base de données confirme que l'événement a déjà été traité. Renvoyer 4xx ou 5xx demande au prestataire de continuer à réessayer.
• Comment tester localement les relances de webhooks ? — Écrivez des tests unitaires déterministes qui envoient deux fois la même charge utile signée et vérifiez qu'une seule licence, un seul droit ou un seul e-mail transactionnel est produit.
• Comment les achats intégrés mobiles s'intègrent-ils au même modèle ? — Faites passer les notifications serveur RevenueCat par la même table idempotente de droits afin que les achats web et mobiles ne s'écrasent jamais mutuellement — consultez la check-list de lancement pour les vérifications avant mise en ligne.