feat(billing): add Stripe webhook endpoint and handler (#3256)

* feat(billing): add Stripe webhook endpoint and event handlers

Add POST /api/billing/webhook pre-parser route with raw body parsing,
signature verification, and handlers for checkout.session.completed,
customer.subscription.updated, customer.subscription.deleted, and
invoice.payment_failed events.

Closes #3243

* test(billing): add unit tests for webhook service and controller

Cover all webhook event handlers (checkout.session.completed,
subscription.updated, subscription.deleted, invoice.payment_failed)
and controller endpoint to meet global coverage thresholds.

* fix(billing): address review feedback — validate IDs, fix resolvePlan, add error logging

- Validate organizationId with ObjectId.isValid before DB operations
- Enable runValidators on Organization plan updates
- Fix resolvePlan to use price.metadata (not price.product.metadata)
  since Stripe webhook payloads return product as string ID
- Fix JSDoc return type to Promise<void>
- Add console.error logging for webhook handler failures
- Update tests to match new behavior

Author: PierreBrisorgueil

modules/billing/controllers/billing.webhook.controller.js

@@ -0,0 +1,71 @@
+/**
+ * Module dependencies
+ */
+import Stripe from 'stripe';
+
+import config from '../../../config/index.js';
+import BillingWebhookService from '../services/billing.webhook.service.js';
+
+/**
+ * Lazily instantiated Stripe client
+ */
+let stripeClient = null;
+
+/**
+ * @desc Get or create the Stripe client instance
+ * @returns {Object|null} Stripe client or null if not configured
+ */
+const getStripe = () => {
+  if (stripeClient) return stripeClient;
+  if (!config.stripe?.secretKey) return null;
+  stripeClient = new Stripe(config.stripe.secretKey);
+  return stripeClient;
+};
+
+/**
+ * @desc Endpoint to handle Stripe webhook events
+ * @param {Object} req - Express request object
+ * @param {Object} res - Express response object
+ * @returns {Promise<void>}
+ */
+const handleWebhook = async (req, res) => {
+  const stripe = getStripe();
+  if (!stripe) return res.status(400).json({ error: 'Stripe is not configured' });
+
+  const sig = req.headers['stripe-signature'];
+  const { webhookSecret } = config.stripe;
+
+  let event;
+  try {
+    event = stripe.webhooks.constructEvent(req.body, sig, webhookSecret);
+  } catch (err) {
+    return res.status(400).json({ error: `Webhook signature verification failed: ${err.message}` });
+  }
+
+  try {
+    switch (event.type) {
+      case 'checkout.session.completed':
+        await BillingWebhookService.handleCheckoutCompleted(event.data.object);
+        break;
+      case 'customer.subscription.updated':
+        await BillingWebhookService.handleSubscriptionUpdated(event.data.object);
+        break;
+      case 'customer.subscription.deleted':
+        await BillingWebhookService.handleSubscriptionDeleted(event.data.object);
+        break;
+      case 'invoice.payment_failed':
+        await BillingWebhookService.handleInvoicePaymentFailed(event.data.object);
+        break;
+      default:
+        break;
+    }
+    return res.status(200).json({ received: true });
+  } catch (err) {
+    console.error('Stripe webhook handler error:', err);
+    return res.status(500).json({ error: 'Webhook handler failed' });
+  }
+};
+
+export default {
+  handleWebhook,
+};

modules/billing/repositories/billing.subscription.repository.js

@@ -97,6 +97,18 @@ const findByStripeCustomerId = (stripeCustomerId) => {
   return Subscription.findOne({ stripeCustomerId: normalized }).populate(defaultPopulate).exec();
 };
 
+/**
+ * @function findByStripeSubscriptionId
+ * @description Data access operation to fetch a subscription by Stripe subscription ID.
+ * @param {String} stripeSubscriptionId - The Stripe subscription ID.
+ * @returns {Promise<Object|null>} A promise resolving to the retrieved subscription or null.
+ */
+const findByStripeSubscriptionId = (stripeSubscriptionId) => {
+  const normalized = stripeSubscriptionId?.trim();
+  if (!normalized) return null;
+  return Subscription.findOne({ stripeSubscriptionId: normalized }).populate(defaultPopulate).exec();
+};
+
 export default {
   list,
   create,
@@ -105,4 +117,5 @@ export default {
   remove,
   findByOrganization,
   findByStripeCustomerId,
+  findByStripeSubscriptionId,
 };

modules/billing/routes/billing.preroute.js

@@ -0,0 +1,15 @@
+/**
+ * Module dependencies
+ */
+import express from 'express';
+
+import webhook from '../controllers/billing.webhook.controller.js';
+
+/**
+ * @desc Register billing pre-parser routes (mounted before body parsing and CSRF)
+ * @param {Object} app - Express application instance
+ * @returns {void}
+ */
+export default (app) => {
+  app.route('/api/billing/webhook').post(express.raw({ type: 'application/json' }), webhook.handleWebhook);
+};

modules/billing/services/billing.webhook.service.js

@@ -0,0 +1,129 @@
+/**
+ * Module dependencies
+ */
+import mongoose from 'mongoose';
+
+import SubscriptionRepository from '../repositories/billing.subscription.repository.js';
+
+const Organization = mongoose.model('Organization');
+
+/**
+ * @desc Resolve the plan name from a Stripe subscription object.
+ * In webhook payloads, price.product is typically a string ID (not expanded),
+ * so we check price.metadata first, then fall back to plan.metadata.
+ * @param {Object} subscription - Stripe subscription object
+ * @returns {string} plan name
+ */
+const resolvePlan = (subscription) => {
+  const item = subscription.items?.data?.[0];
+  return item?.price?.metadata?.planId || item?.plan?.metadata?.planId || 'free';
+};
+
+/**
+ * @desc Sync the organization plan field to match the subscription plan
+ * @param {String} organizationId - Organization document ID
+ * @param {String} plan - Plan name to set
+ * @returns {Promise<void>}
+ */
+const syncOrganizationPlan = async (organizationId, plan) => {
+  if (!organizationId || !mongoose.Types.ObjectId.isValid(organizationId)) return;
+  await Organization.findByIdAndUpdate(organizationId, { plan }, { runValidators: true }).exec();
+};
+
+/**
+ * @desc Handle checkout.session.completed event — create or update subscription
+ * @param {Object} session - Stripe checkout session object
+ * @returns {Promise<void>}
+ */
+const handleCheckoutCompleted = async (session) => {
+  const { customer: stripeCustomerId, subscription: stripeSubscriptionId, metadata } = session;
+  const organizationId = metadata?.organizationId;
+  const plan = metadata?.plan || 'free';
+
+  if (!organizationId || !mongoose.Types.ObjectId.isValid(organizationId)) return;
+
+  const existing = await SubscriptionRepository.findByOrganization(organizationId);
+  if (existing) {
+    await SubscriptionRepository.update({
+      _id: existing._id,
+      stripeCustomerId,
+      stripeSubscriptionId,
+      plan,
+      status: 'active',
+    });
+  } else {
+    await SubscriptionRepository.create({
+      organization: organizationId,
+      stripeCustomerId,
+      stripeSubscriptionId,
+      plan,
+      status: 'active',
+    });
+  }
+
+  await syncOrganizationPlan(organizationId, plan);
+};
+
+/**
+ * @desc Handle customer.subscription.updated event — sync subscription state
+ * @param {Object} subscription - Stripe subscription object
+ * @returns {Promise<void>}
+ */
+const handleSubscriptionUpdated = async (subscription) => {
+  const existing = await SubscriptionRepository.findByStripeSubscriptionId(subscription.id);
+  if (!existing) return;
+
+  const plan = resolvePlan(subscription);
+  await SubscriptionRepository.update({
+    _id: existing._id,
+    plan,
+    status: subscription.status,
+    currentPeriodEnd: new Date(subscription.current_period_end * 1000),
+    cancelAtPeriodEnd: subscription.cancel_at_period_end,
+  });
+
+  await syncOrganizationPlan(existing.organization?._id || existing.organization, plan);
+};
+
+/**
+ * @desc Handle customer.subscription.deleted event — cancel subscription
+ * @param {Object} subscription - Stripe subscription object
+ * @returns {Promise<void>}
+ */
+const handleSubscriptionDeleted = async (subscription) => {
+  const existing = await SubscriptionRepository.findByStripeSubscriptionId(subscription.id);
+  if (!existing) return;
+
+  await SubscriptionRepository.update({
+    _id: existing._id,
+    plan: 'free',
+    status: 'canceled',
+  });
+
+  await syncOrganizationPlan(existing.organization?._id || existing.organization, 'free');
+};
+
+/**
+ * @desc Handle invoice.payment_failed event — mark subscription as past_due
+ * @param {Object} invoice - Stripe invoice object
+ * @returns {Promise<void>}
+ */
+const handleInvoicePaymentFailed = async (invoice) => {
+  const { subscription: stripeSubscriptionId } = invoice;
+  if (!stripeSubscriptionId) return;
+
+  const existing = await SubscriptionRepository.findByStripeSubscriptionId(stripeSubscriptionId);
+  if (!existing) return;
+
+  await SubscriptionRepository.update({
+    _id: existing._id,
+    status: 'past_due',
+  });
+};
+
+export default {
+  handleCheckoutCompleted,
+  handleSubscriptionUpdated,
+  handleSubscriptionDeleted,
+  handleInvoicePaymentFailed,
+};