← Retour au blog
BillingPublié 2026-03-21· 12 min de lecture

Facturation d'abonnement Next.js : webhooks fiables

WangNan, author at Uncorne
Publié par Uncorne · Mis à jour 2026-10-09

La plupart des tutoriels de facturation par abonnement s'arrêtent au chemin nominal : créer une session de paiement, rediriger le navigateur, et terminé. Cela fonctionne en démo. Cela échoue dès qu'un client ferme l'onglet en cours de paiement, qu'un fournisseur renvoie un événement, ou qu'un test se déclenche deux fois. La facturation de production vit dans les parties que ces tutoriels passent sous silence. Voici le contrat utilisé par les applications générées par Uncorne — cinq fournisseurs de paiement derrière une seule couche de vérification et de droits — et la raison de chaque règle.

Flux de webhook de facturation d'abonnement Next.js
Flux de webhook de facturation d'abonnement Next.js

Le navigateur n'est pas la source de vérité

Une redirection réussie est un indice, pas un fait. Le client peut fermer l'onglet après avoir payé mais avant le chargement de votre page de succès. Un webhook peut arriver avant la redirection, deux fois, ou pas du tout si la vérification de signature échoue. Traitez la redirection comme un simple écran de remerciement cosmétique, rien de plus.

Votre base de données est l'unique source de vérité, et une seule chose est autorisée à y écrire l'état de l'abonnement : un webhook vérifié provenant du fournisseur. Tout le reste — la page de succès, un appel d'interrogation de l'API du fournisseur, la note d'un agent du support — ne fait que lire cette base. Inversez cela et vous finirez par accorder l'accès à quelqu'un qui n'a pas payé, ou le retirer à quelqu'un qui a payé. L'aperçu officiel des abonnements Stripe énumère les événements du cycle de vie à traiter ; la règle pratique est d'en traiter moins, de bien les traiter, et d'ignorer les autres explicitement plutôt que silencieusement.

Le contrat de vérification, énoncé précisément

La vérification de signature doit être la première chose que fait votre route — avant d'analyser un corps, avant de toucher à la base, avant de journaliser quoi que ce soit contenant des données client. Le contrat mérite d'être écrit, car l'inverser est un bug de sécurité, pas une préférence de style :

  • Signature absente, invalide ou mal formée → lever une erreur. La route répond 400 et n'écrit rien.
  • Événement correctement signé mais ne nécessitant aucun traitement → renvoyer un résultat vide et un 200 avec un indicateur ignored.
  • Identifiant d'événement déjà vu → ignorer avant toute écriture.
  • Événement valide, inédit et à traiter → écrire, puis enregistrer l'identifiant dans la même transaction.

Une version antérieure des adaptateurs Uncorne renvoyait une liste vide en cas d'échec de vérification. Cela signifiait qu'une requête forgée était acquittée par un 200. Nous avons modifié cela pour qu'un échec de vérification lève une erreur avant que la route ne puisse acquitter quoi que ce soit. Ne faites pas ce compromis — un 200 est une promesse, et vous ne devez le faire qu'après avoir vérifié la signature comme décrit dans le guide de signature des webhooks Stripe.

export async function POST(req: Request) {
  const raw = await req.text();               // vérifier sur le corps BRUT
  let event: ProviderEvent;
  try {
    event = verifyAndParse(raw, req.headers); // lève une erreur si signature invalide
  } catch {
    return new Response("invalid signature", { status: 400 });
  }
  if (shouldIgnore(event)) {
    return json({ ignored: true, handled: [] });
  }
  const fresh = await markSeen(event.id);     // insertion atomique, false si doublon
  if (!fresh) return json({ ignored: true, duplicate: true });
  await applyPlanChange(event);               // écrit customer -> plan
  return json({ handled: [event.type] });
}

Vérifiez sur le corps brut de la requête, jamais sur un objet resérialisé. L'ordre des clés JSON et les espaces ne sont pas stables d'un fournisseur ou d'une version de SDK à l'autre, et la resérialisation est une façon classique d'invalider une signature pourtant correcte. Lisez le corps une fois avec req.text(), transmettez ces octets exacts au vérificateur, puis seulement analysez-les en objet.

Séquence de vérification de signature de webhook
Séquence de vérification de signature de webhook

L'idempotence n'est pas optionnelle

Les fournisseurs renvoient des événements. Un webhook accordant un forfait sera livré à nouveau si votre endpoint est lent, renvoie une erreur 500, ou expire. Sans étape de déduplication, la seconde livraison peut réinitialiser le quota d'un utilisateur, prolonger un abonnement deux fois, ou envoyer un second e-mail de bienvenue. Créez une table qui enregistre chaque identifiant d'événement traité :

create table webhook_events (
  provider   text not null,
  event_id   text not null,
  type       text not null,
  received_at timestamptz not null default now(),
  primary key (provider, event_id)
);

L'insertion est la barrière : utilisez une insertion atomique qui renvoie false en cas de conflit, et ne continuez que lorsqu'elle renvoie true. Avec Supabase, c'est un upsert avec onConflict et une branche de résolution de conflit ; avec le chemin SQLite local, c'est un INSERT ... ON CONFLICT DO NOTHING suivi d'une vérification du nombre de lignes modifiées. Placez la déduplication dans la même transaction que l'écriture du forfait lorsque votre base le permet, afin qu'un plantage ne laisse pas un événement enregistré avec un forfait inchangé. Conservez les lignes au moins aussi longtemps que la fenêtre de renvoi du fournisseur — Stripe renvoie jusqu'à trois jours, donc 30 jours de rétention offrent une marge confortable.

Contrôlez les droits côté serveur, jamais dans l'interface

Masquer un bouton n'est pas un contrôle d'accès. Lisez le forfait depuis la session ou la base sur chaque route protégée, et prenez la décision là. Dans l'App Router, cela signifie un gestionnaire de route ou une Server Action qui lit le cookie de session avec cookies() et consulte le droit — pas un composant client qui vérifie une prop. Si le forfait est inactif, l'endpoint IA renvoie 402, même si quelqu'un modifie le DOM dans les devtools ou appelle l'API directement avec curl.

export async function POST(req: Request) {
  const session = await getSession();
  if (!session?.user) return new Response("unauthorized", { status: 401 });
  const entitlement = await getEntitlement(session.user.id);
  if (!entitlement.active) {
    return Response.json({ code: "no_entitlement" }, { status: 402 });
  }
  return streamAnswer(req, session.user.id);
}

Il en va de même pour les Server Actions et mutations : autorisez dans l'action, pas dans le composant qui affiche le formulaire. Les vérifications côté client sont pour l'ergonomie ; celles côté serveur sont pour la sécurité. Si vous n'en faites qu'une, faites celle du serveur. Une habitude utile est d'écrire d'abord la vérification serveur et de traiter l'interface comme le reflet d'une décision déjà prise.

Flux de contrôle de forfait côté serveur
Flux de contrôle de forfait côté serveur

402 et 429 sont deux réponses différentes

Deux modes d'échec sont constamment confondus. Un 402 signifie qu'il n'y a aucun droit — pas de licence valide, pas d'abonnement actif, pas de revendication d'e-mail vérifiée. Un 429 signifie que le client a un droit mais a épuisé un quota d'usage. Les mélanger rend les tableaux de bord trompeurs et le support pénible, car le correctif de l'un est « acheter un forfait » et celui de l'autre est « attendre la réinitialisation ».

| Statut | Code | Signification | Ce que le client doit faire | | --- | --- | --- | --- | | 402 | no_entitlement | Aucune licence ou abonnement actif | Ouvrir le portail de facturation | | 402 | preview_limit_reached | Quota d'aperçu anonyme épuisé | Inviter à s'inscrire | | 429 | quota_exceeded | Quota IA quotidien épuisé | Afficher l'heure de réinitialisation | | 400 | invalid_signature | Échec de vérification du webhook | Rien — côté serveur uniquement |

Le statut de l'abonnement n'est pas la même chose que les limites d'usage. L'endpoint IA possède son propre quota quotidien par utilisateur (AI_MESSAGES_PER_DAY, par défaut 50) adossé à un RPC Supabase ou à la table SQLite locale ai_usage. Lorsqu'il est épuisé, renvoyez 429 avec un en-tête X-AI-Quota-Reset et un Retry-After honnête en secondes calculé à partir de l'horodatage réel de réinitialisation — pas un 86400 codé en dur. Un faux indice de renvoi est pire que rien : il habitue les clients à ignorer l'en-tête et oblige le support à deviner.

Un contrat de paiement, cinq fournisseurs

Uncorne fournit des adaptateurs pour Waffo, Stripe, Creem, PayPal et Lemon Squeezy derrière une interface unique. Chaque adaptateur mappe les événements du fournisseur vers un petit vocabulaire interne — activated, renewed, cancelled, past due — et la couche de droits ne comprend que ce vocabulaire. Changer de fournisseur devient alors une modification de configuration plus une mise à jour d'URL de webhook, pas une réécriture de votre code produit. L'API Stripe Checkout Sessions est une bonne référence pour les champs à normaliser : identifiant client, identifiant d'abonnement, identifiant de prix et fin de période en cours.

Le compromis est honnête : un contrat commun est un dénominateur commun. Les fonctionnalités propres à un fournisseur, comme la facturation à l'usage ou la gestion fiscale d'un Merchant of Record, nécessitent une porte de sortie. Conservez une méthode d'adaptateur pour les données spécifiques au fournisseur et documentez qu'elle est volontairement non portable, afin que personne ne croie que l'abstraction est magique.

Cinq adaptateurs de paiement derrière un contrat unique
Cinq adaptateurs de paiement derrière un contrat unique

Remboursements, annulations et ce que « actif » signifie vraiment

Un abonnement peut être actif dans un système et remboursé dans un autre. Écoutez également les événements de remboursement et de litige, et traitez un remboursement intégral comme une révocation immédiate plutôt que d'attendre la fin de période. Pour les annulations, préférez cancel_at_period_end afin que le client conserve l'accès pendant la période payée et que vous évitiez un ticket de support sur une perte de données dès le premier jour.

Stockez le statut brut du fournisseur à côté de votre droit normalisé, et ne déduisez jamais « actif » d'un booléen positionné une fois à l'inscription. Recalculez-le à la lecture à partir du dernier événement appliqué. Ce seul changement corrige une surprenante catégorie de bugs où le forfait semble correct en base mais erroné dans le produit.

Testez l'invariant de sécurité hors ligne

Vous n'avez pas besoin de cinq comptes sandbox pour valider le contrat. Uncorne inclut une sonde de signature hors ligne — npm run probe:webhook — qui envoie quatre corps à un serveur en cours d'exécution : signature valide, signature absente, signature corrompue et JSON mal formé. Elle vérifie les codes de statut du tableau ci-dessus, si bien qu'une régression qui acquitte un événement forgé avec un 200 échoue en CI. Le guide des webhooks Stripe documente les types d'événements qu'un vrai sandbox livrera ; utilisez cette liste pour construire vos scénarios de bout en bout.

Les quatre couches, par réalisme croissant :

  1. Tests unitaires de la fonction de vérification avec des fixtures fixes.
  2. La sonde hors ligne contre un serveur de développement en cours d'exécution — aucun identifiant requis.
  3. Exécutions sandbox de bout en bout avec les clés de test de chaque fournisseur, y compris un vrai renvoi.
  4. Un petit canari en production après déploiement : un abonnement de faible montant, remboursé immédiatement.

Les couches 1 et 2 appartiennent à la CI et doivent être rapides. Les couches 3 et 4 sont une barrière avant publication. Sauter la couche hors ligne est l'erreur courante : c'est la seule qui détecte le bug « renvoyer 200 en cas d'échec » sans dépendre d'un service externe.

Sortie de la sonde de webhook hors ligne
Sortie de la sonde de webhook hors ligne

Modes de défaillance à anticiper

Quelques situations sont assez rares pour être oubliées et assez fréquentes pour faire mal. Un webhook de renouvellement arrive en retard, après que votre cron a déjà révoqué l'accès — corrigez en recalculant le droit depuis l'état actuel du fournisseur plutôt qu'en appliquant les événements isolément. Un client change de forfait et deux événements arrivent dans le désordre — stockez l'horodatage de fin de période et ignorez les événements plus anciens que celui déjà appliqué. Un webhook est correctement signé mais référence un identifiant client que vous n'avez pas encore — mettez-le en file et réessayez après la création de l'utilisateur au lieu de le supprimer.

L'observabilité compte ici. Journalisez l'identifiant et le type de l'événement ainsi que la décision prise (handled, ignored, duplicate, failed) avec un identifiant client haché. Ne journalisez pas le corps brut ; il contient des données personnelles et éventuellement un jeton de moyen de paiement. Lorsqu'un client dit « j'ai payé mais je suis toujours bloqué », vous devez pouvoir répondre en une requête quels événements sont arrivés et ce que vous en avez fait.

Courte liste de contrôle avant publication

  • La vérification sur corps brut lève une erreur en cas d'échec et ne renvoie jamais 200.
  • Chaque identifiant d'événement traité est enregistré atomiquement avant l'écriture du forfait.
  • Les routes protégées lisent le droit côté serveur ; aucun contrôle uniquement client.
  • 402 et 429 portent des codes stables lisibles par machine et des en-têtes de renvoi honnêtes.
  • La sonde hors ligne s'exécute en CI à chaque pull request.
  • Au moins une exécution sandbox de bout en bout par fournisseur avant publication.

Pour le parcours complet de création des produits et de la route de paiement, lisez Ajouter des abonnements Stripe à Next.js. Pour la place de la facturation dans un starter, voir Que vérifier dans un boilerplate SaaS Next.js avec Stripe et auth.

La facturation par abonnement n'est pas difficile parce que les API sont difficiles. Elle l'est parce que les cas limites restent invisibles jusqu'à ce qu'un vrai client les rencontre. Écrivez le contrat, testez l'invariant hors ligne, et laissez le webhook — pas le navigateur — décider qui a accès.

FAQ

Une redirection du navigateur suffit-elle à accorder un accès payant ?+

Non. Une redirection est un indice, pas une preuve de paiement. Seul un webhook vérifié doit écrire l'état de l'abonnement dans votre base ; tout le reste, y compris la page de succès, ne fait que la lire. Cela empêche l'accès aux utilisateurs qui ferment l'onglet avant de payer ou qui rejouent un callback.

Comment rendre un webhook idempotent ?+

Stockez l'identifiant d'événement du fournisseur dans une table webhook_events avec une clé primaire sur (provider, event_id), et effectuez une insertion atomique avant toute écriture de forfait ou de licence. La vérification passe d'abord ; seuls les événements vérifiés et non traités atteignent la déduplication. Stripe renvoie jusqu'à trois jours : conservez les lignes au moins 30 jours.

Quelle est la différence entre 402 et 429 dans une application d'abonnement ?+

402 signifie qu'il n'y a aucun droit — aucune licence valide, aucun abonnement actif, aucune revendication d'e-mail vérifiée. 429 signifie que le client a un droit mais a épuisé le quota IA quotidien. L'épuisement du quota d'aperçu est un 402 distinct avec un code preview_limit_reached. On corrige un 402 en achetant un forfait et un 429 en attendant la réinitialisation.

Comment vérifier les signatures de webhook dans Next.js ?+

Lisez une fois le corps brut de la requête avec req.text() et transmettez ces octets exacts au vérificateur avant de le parser en objet. Levez une erreur sur une signature absente, invalide ou mal formée pour que la route réponde 400 et n'écrive rien. Resérialiser le JSON au préalable peut invalider une signature correcte, car l'ordre des clés et les espaces varient.

Puis-je tester la facturation sans comptes sandbox ?+

Vous pouvez valider le contrat de vérification commun hors ligne avec npm run probe:webhook, qui envoie des corps valide, manquant, corrompu et mal formé à un serveur actif et vérifie les codes de statut. Le vrai parcours de paiement de chaque passerelle nécessite encore ses identifiants sandbox avant publication ; voir docs/payment-testing.md pour la stratégie en quatre couches.

Toutes les questions fréquentes · Version Markdown (pour les agents IA)