Webhook Events

// From src/lib/better-auth/auth.ts
stripe({
  stripeClient,
  stripeWebhookSecret: env.STRIPE_WEBHOOK_SECRET,
  createCustomerOnSignUp: true,
  subscription: {
    enabled: true,
    // Automatic event handlers...
    onSubscriptionComplete: async ({ subscription }) => { /* ... */ },
    onSubscriptionUpdate: async ({ subscription }) => { /* ... */ },
    onSubscriptionCancel: async ({ subscription }) => { /* ... */ },
    onSubscriptionDeleted: async ({ subscription }) => { /* ... */ },
  },
  onEvent: onStripeEvent, // Custom event handler
})

// From src/lib/stripe/stripe-events.ts
export const onStripeEvent = async (event: Stripe.Event) => {
  console.log(`Processing Stripe event: ${event.type}`)

  // Custom business logic for events not handled by Better Auth
  switch (event.type) {
    case 'invoice.payment_failed':
      // Handle failed payments
      break
    case 'customer.subscription.trial_will_end':
      // Send trial ending notifications
      break
    default:
      // Log unhandled events
      console.log(`Unhandled event type: ${event.type}`)
  }
}

// From src/lib/stripe/stripe-events.ts
case 'checkout.session.completed': {
  const session = event.data.object as Stripe.Checkout.Session
  const isCustomCheckout = session.metadata?.source === 'custom_checkout'

  // Handle guest checkout with automatic user creation
  if (isCustomCheckout) {
    await handleGuestCheckoutSessionCompleted(session)
  }

  // Handle installment checkout
  const isInstallmentCheckout = session.metadata?.source === 'installment_checkout'
  if (isInstallmentCheckout) {
    await handleInstallmentCheckoutSessionCompleted(session)
  }
  break
}

// From src/lib/stripe/stripe-events.ts
async function handleInstallmentCheckoutSessionCompleted(session: Stripe.Checkout.Session) {
  // 1. Validate installment data (schedule_id, number_of_payments)
  const installmentData = validateInstallmentCheckoutData(session, metadata)

  // 2. Handle user creation (guest or authenticated)
  const finalUser = isGuestCheckout
    ? await createGuestUser(customerData)
    : await getAuthenticatedUser(customerEmail)

  // 3. Create subscription with installment periods
  await createInstallmentSubscription(installmentData, finalUser)
}

// Custom handling for payment failures
case 'invoice.payment_failed':
  const invoice = event.data.object as Stripe.Invoice

  // Custom business logic
  await handlePaymentFailure({
    customerId: invoice.customer as string,
    invoiceId: invoice.id,
    amountDue: invoice.amount_due,
    attemptCount: invoice.attempt_count,
  })
  break

// Custom trial ending notifications
case 'customer.subscription.trial_will_end':
  const subscription = event.data.object as Stripe.Subscription

  await sendTrialExpirationNotification({
    customerId: subscription.customer as string,
    subscriptionId: subscription.id,
    trialEnd: new Date(subscription.trial_end! * 1000),
  })
  break

// Handle metered billing events
case 'invoice.upcoming':
  const upcomingInvoice = event.data.object as Stripe.Invoice

  // Calculate usage charges before invoice finalization
  await calculateUsageCharges({
    customerId: upcomingInvoice.customer as string,
    periodStart: new Date(upcomingInvoice.period_start * 1000),
    periodEnd: new Date(upcomingInvoice.period_end * 1000),
  })
  break

onSubscriptionComplete: async ({ subscription }) => {
  // Automatic Better Auth processing:
  // 1. Update user's subscription status in database
  // 2. Send welcome email notification
  // 3. Grant access to premium features
  // 4. Update usage limits
  // 5. Log subscription event for analytics
}

onSubscriptionUpdate: async ({ subscription }) => {
  // Automatic Better Auth processing:
  // 1. Update subscription details in database
  // 2. Adjust user access levels
  // 3. Send plan change confirmation email
  // 4. Update feature limitations
  // 5. Prorate billing if necessary
}

onSubscriptionCancel: async ({ subscription }) => {
  // Automatic Better Auth processing:
  // 1. Mark subscription as canceled
  // 2. Send cancellation confirmation
  // 3. Schedule access removal (if immediate)
  // 4. Trigger win-back campaign
  // 5. Update customer success metrics
}

// Automatic signature verification by Better Auth
stripe({
  stripeWebhookSecret: env.STRIPE_WEBHOOK_SECRET, // Used for verification
})

export const onStripeEvent = async (event: Stripe.Event) => {
  console.log(`Processing Stripe event: ${event.type}`)
  console.log(`Event ID: ${event.id}`)
  console.log(`Created: ${new Date(event.created * 1000).toISOString()}`)

  try {
    // Process event
    await processCustomEvent(event)
    console.log(`✅ Successfully processed ${event.type}`)
  } catch (error) {
    console.error(`❌ Error processing ${event.type}:`, error)
    throw error // Let Better Auth handle retry logic
  }
}