Webhooks Stripe | API Monsiteo

Monsiteo ne vérifie jamais l'état d'un abonnement en interrogeant Stripe à chaque requête : il le reçoit par webhooks. Chaque événement Stripe utile met à jour l'abonnement, les paiements et la formule du compte, puis déclenche les e-mails correspondants.

Bon à savoir Cette page concerne l'équipe technique de Monsiteo et les personnes qui installent leur propre instance. Les clients n'ont rien à configurer.

Point d'entrée#

POST https://api.monsiteo.com/stripe/webhook

Attention : cette route est hors du préfixe /v1. Elle n'utilise ni jeton ni protection CSRF ; l'authenticité est garantie par la signature Stripe.

En-tête	Rôle
`Stripe-Signature`	Signature HMAC de Stripe, vérifiée avec le secret du point de terminaison (`STRIPE_WEBHOOK_SECRET`, commence par `whsec_`).

Le corps est l'événement Stripe brut (JSON), lu tel quel : aucun proxy ne doit le modifier.

Réponses#

Code	Corps	Signification
`200`	`{"received": true}`	Événement accepté (traité, ou ignoré s'il n'est pas utile).
`400`	`{"message": "Signature invalide"}`	Signature absente, invalide ou expirée, ou corps illisible.
`500`	`{"message": "Erreur de traitement"}`	Erreur pendant le traitement ; l'erreur est journalisée. Stripe renverra l'événement plus tard.
`503`	`{"message": "Webhook non configuré"}`	Le secret du webhook n'est pas configuré sur le serveur.

Stripe réessaie automatiquement les événements qui n'ont pas reçu de 2xx, pendant plusieurs jours. Le traitement est idempotent : les abonnements sont retrouvés par leur identifiant Stripe et les paiements par l'identifiant de facture, un événement reçu deux fois ne crée donc pas de doublon.

Événements traités#

L'utilisateur concerné est retrouvé grâce à metadata.user_id (posé lors de la création de la session Checkout), ou à défaut grâce à l'identifiant client Stripe enregistré sur le compte.

Événement	Effet dans Monsiteo
`customer.subscription.created`	Crée ou met à jour l'abonnement local (formule déduite du prix Stripe, rythme mensuel ou annuel, statut, fin d'essai, fin de période, résiliation programmée). Clôture les autres abonnements en cours du compte, applique la formule (affichage ou non de la mention « Créé avec Monsiteo » sur les sites). Pour un nouvel abonnement en essai ou actif : journal d'activité et e-mail « abonnement démarré ». Pour Site + Novadesko : lance la liaison du compte Novadesko.
`customer.subscription.updated`	Même traitement que `created` (changement de formule, fin d'essai, impayé, résiliation programmée ou annulée...).
`customer.subscription.deleted`	Passe l'abonnement en `canceled`, réapplique la formule (retour en Gratuit) et envoie l'e-mail « abonnement résilié ».
`customer.subscription.trial_will_end`	Envoie l'e-mail « votre essai se termine bientôt » (Stripe l'émet 3 jours avant la fin de l'essai).
`invoice.paid`	Enregistre le paiement (numéro, montant, TVA, devise, lien PDF de la facture) et envoie l'e-mail « facture payée ». Les factures à 0 € (début d'essai) sont ignorées.
`invoice.payment_failed`	Enregistre le paiement en échec et envoie l'e-mail « échec de paiement ».

Correspondance des statuts Stripe :

Statut Stripe	Statut Monsiteo	Accès aux fonctions payantes
`trialing`	`trialing`	oui, jusqu'à la fin de l'essai
`active`	`active`	oui
`past_due`, `unpaid`, `incomplete`	`past_due`	oui (période de grâce pendant les relances)
`canceled`, `incomplete_expired`	`canceled`	jusqu'à la date de fin si elle est future
autre	`expired`	non

Tous les autres types d'événements reçoivent 200 et sont ignorés.

Configuration côté Stripe#

Dans le tableau de bord Stripe, ouvrez Développeurs, Webhooks, puis ajoutez un point de terminaison.
URL : https://api.monsiteo.com/stripe/webhook.
Sélectionnez au minimum les événements : customer.subscription.created, customer.subscription.updated, customer.subscription.deleted, customer.subscription.trial_will_end, invoice.paid, invoice.payment_failed.
Copiez le secret de signature (whsec_...) dans la variable d'environnement STRIPE_WEBHOOK_SECRET du serveur.
Vérifiez que les identifiants de prix des formules sont configurés (STRIPE_PRICE_SITE_MONTHLY, STRIPE_PRICE_SITE_YEARLY, STRIPE_PRICE_SITE_NOVADESKO_MONTHLY, STRIPE_PRICE_SITE_NOVADESKO_YEARLY) : ils servent à reconnaître la formule d'un abonnement.

Attention Le mode test et le mode réel de Stripe ont des secrets de webhook différents. Un secret de test sur le serveur de production fait échouer toutes les signatures (400).

Tester en local avec la CLI Stripe#

# 1. Relayer les événements de votre compte Stripe (mode test) vers votre poste
stripe listen --forward-to http://api.monsiteo.localhost:8000/stripe/webhook

# 2. La commande affiche un secret "whsec_..." : placez-le dans .env
#    STRIPE_WEBHOOK_SECRET=whsec_...

# 3. Dans un autre terminal, déclenchez des événements de test
stripe trigger customer.subscription.created
stripe trigger invoice.paid
stripe trigger invoice.payment_failed

Les événements générés par stripe trigger ne portent pas de metadata.user_id et concernent un client Stripe inconnu de Monsiteo : ils sont acceptés (200) mais ignorés (un avertissement est journalisé pour les événements d'abonnement). Pour tester le parcours complet, souscrivez depuis l'application avec la carte de test 4242 4242 4242 4242 pendant que stripe listen tourne.