Stop Making Users Refresh to See Their Subscription Status

Most tutorials are bullshit.

Most tutorials show you the happy path: payment goes through, webhook hits your API, database updates, done. Sounds great until you realize your users are sitting there wondering if their $99/month payment actually worked.

I've debugged this exact scenario way too many times: "I paid but my dashboard still shows Free Plan!" Meanwhile, the payment went through 5 minutes ago, but the UI never updated.

The problem? Those tutorials skip the part where your UI actually updates without forcing users to refresh the page like it's 2015.

The Bullshit User Experience Most Apps Have

Here's what actually happens with basic webhook integration:

1. User pays $29/month for your SaaS
2. Stripe processes payment (user gets charged immediately)
3. Webhook fires and updates your database 3-8 seconds later
4. User lands back on your dashboard seeing "Free Plan"
5. User panics and emails support: "I was charged but nothing changed!"
6. You debug for 20 minutes just to tell them "try refreshing the page"

This broken flow exists in most SaaS apps I've tried. The fix is Supabase Real-time but most tutorials treat it like optional nice-to-have instead of core UX.

How Supabase Real-time Actually Works (And Why It Randomly Fails)

Here's how Supabase Real-time actually works under the hood - it's built on Phoenix's real-time stuff, which means it's pretty solid but has its quirks.

Basically, when your database row changes, Real-time catches it and pushes the update to connected clients. Works great... until it doesn't.

What you actually get with Real-time:

• Database Changes: Listens to INSERT, UPDATE, DELETE - but only if your RLS policies don't block it
• Presence: Track online users (works well when connections don't randomly drop)
• Broadcast: Send messages to all subscribers - useful for "your subscription expires in 5 minutes" warnings
• Channel filtering: Target specific users - absolutely critical or everyone sees everyone else's data

Real-time Subscription Flow That Actually Works

Here's how the integration should work with real-time capabilities:

1. User initiates payment → Stripe Checkout
2. Payment succeeds → Stripe webhook fires immediately  
3. Webhook updates Supabase database → Real-time detects change
4. Real-time pushes update to all user's connected clients
5. UI updates instantly without page refresh

Critical Implementation Details (AKA Things That Will Break):

Your webhook handler needs the service role key to bypass RLS policies. I learned this at 11pm on a Friday when payments were going through but subscription statuses weren't updating.

The fun part? No error messages anywhere. Stripe webhooks: 200 OK. My API logs: everything looks fine. Users: "I paid but nothing changed!"

Took me 2 hours of digging through Supabase logs to find: new row violates row-level security policy for table \"profiles\" (exact error from logs). The webhook was hitting my API, my API was calling Supabase, but RLS was silently blocking the updates.

Fixed it with this RLS policy:

CREATE POLICY \"Service role can update any profile\" ON public.profiles
  FOR UPDATE USING (auth.role() = 'service_role');

Here's the RLS troubleshooting guide that saved my ass when this happened.

Other fun RLS failures: service role updates work but users can't read their own data, or updates work in dev but fail in prod because you forgot the service role policy.

Client-side real-time subscriptions should use the anon key and respect RLS policies. Don't fuck this up or users will see each other's subscription data (yes, I've seen this in production).

Database Schema for Real-time Subscriptions

Your database schema needs to support both webhook updates and real-time notifications without the usual auth fuckery. Here's the essential table structure:

-- Enhanced profiles table with real-time subscription tracking
CREATE TABLE public.profiles (
  id UUID REFERENCES auth.users(id) ON DELETE CASCADE,
  email TEXT NOT NULL,
  full_name TEXT,
  stripe_customer_id TEXT UNIQUE,
  
  -- Subscription state fields for real-time sync
  subscription_id TEXT,
  subscription_status TEXT DEFAULT 'inactive',
  subscription_tier TEXT,
  current_period_start TIMESTAMPTZ,
  current_period_end TIMESTAMPTZ,
  
  -- Real-time sync metadata
  last_webhook_event TEXT, -- Track latest processed webhook ID
  sync_status TEXT DEFAULT 'synced', -- 'synced', 'pending', 'error'
  
  created_at TIMESTAMPTZ DEFAULT timezone('utc'::text, now()),
  updated_at TIMESTAMPTZ DEFAULT timezone('utc'::text, now()),
  PRIMARY KEY (id)
);

-- Enable RLS and real-time
ALTER TABLE public.profiles ENABLE ROW LEVEL SECURITY;
ALTER PUBLICATION supabase_realtime ADD TABLE public.profiles;

-- RLS policies for secure real-time access
CREATE POLICY \"Users can view own profile\" ON public.profiles
  FOR SELECT USING (auth.uid() = id);

CREATE POLICY \"Service role can update profiles\" ON public.profiles
  FOR UPDATE USING (auth.role() = 'service_role');

RLS Policy Considerations:

The auth.role() = 'service_role' policy ensures that only webhook handlers using the service role key can update subscription data, preventing unauthorized client-side modifications while still allowing real-time updates to flow to authenticated users.

Next.js Real-time Client Setup

Setting up the client-side real-time subscription requires careful handling of authentication state and connection lifecycle:

// hooks/useRealtimeSubscription.ts
import { useEffect, useState } from 'react'
import { createClient } from '@/lib/supabase/client'
import { User } from '@supabase/supabase-js'

interface SubscriptionState {
  subscription_status: string
  subscription_tier: string | null
  current_period_end: string | null
  sync_status: 'synced' | 'pending' | 'error'
}

export function useRealtimeSubscription(user: User | null) {
  const [subscriptionState, setSubscriptionState] = useState<SubscriptionState | null>(null)
  const [isConnected, setIsConnected] = useState(false)
  
  useEffect(() => {
    if (!user) {
      setSubscriptionState(null)
      setIsConnected(false)
      return
    }

    const supabase = createClient()
    
    // Initial subscription state fetch
    const fetchInitialState = async () => {
      const { data } = await supabase
        .from('profiles')
        .select('subscription_status, subscription_tier, current_period_end, sync_status')
        .eq('id', user.id)
        .single()
      
      if (data) setSubscriptionState(data)
    }
    
    fetchInitialState()

    // Set up real-time subscription
    const channel = supabase
      .channel(`profile-changes-${user.id}`)
      .on(
        'postgres_changes',
        {
          event: 'UPDATE',
          schema: 'public',
          table: 'profiles',
          filter: `id=eq.${user.id}`,
        },
        (payload) => {
          // Finally! A webhook that actually worked
          console.log('Real-time subscription update:', payload.new)
          setSubscriptionState(payload.new as SubscriptionState)
        }
      )
      .subscribe((status) => {
        setIsConnected(status === 'SUBSCRIBED')
      })

    // Cleanup on unmount or user change
    return () => {
      supabase.removeChannel(channel)
      setIsConnected(false)
    }
  }, [user?.id]) // Re-subscribe when user changes

  return { subscriptionState, isConnected }
}

Enhanced Webhook Handler with Real-time Events

The webhook handler needs modification to work seamlessly with real-time subscriptions:

// app/api/webhooks/stripe/route.ts
import { headers } from 'next/headers'
import { NextRequest, NextResponse } from 'next/server'
import Stripe from 'stripe'
import { createClient } from '@/lib/supabase/server'

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: '2024-04-10' // Latest stable version - always check Stripe docs
})

export async function POST(req: NextRequest) {
  const body = await req.text()
  const signature = headers().get('stripe-signature')!
  
  let event: Stripe.Event

  try {
    event = stripe.webhooks.constructEvent(
      body, 
      signature, 
      process.env.STRIPE_WEBHOOK_SECRET!
    )
  } catch (err) {
    // This fails for the stupidest reasons - wrong secret, URL encoding issues, etc.
    console.error('Webhook signature verification failed:', err)
    return NextResponse.json({ error: 'Invalid signature' }, { status: 400 })
  }

  // Use service role client for database updates
  const supabase = createClient()
  
  try {
    switch (event.type) {
      case 'customer.subscription.created':
      case 'customer.subscription.updated':
        await handleSubscriptionUpdate(supabase, event)
        break
      
      case 'customer.subscription.deleted':
        await handleSubscriptionCancellation(supabase, event)
        break
        
      case 'invoice.payment_succeeded':
        await handleSuccessfulPayment(supabase, event)
        break
        
      case 'invoice.payment_failed':
        await handleFailedPayment(supabase, event)
        break
    }

    return NextResponse.json({ received: true })
  } catch (error) {
    console.error('Webhook processing error:', error)
    return NextResponse.json(
      { error: 'Webhook processing failed' }, 
      { status: 500 }
    )
  }
}

async function handleSubscriptionUpdate(supabase: any, event: Stripe.Event) {
  const subscription = event.data.object as Stripe.Subscription
  
  // Enhanced update with real-time friendly data structure
  const { error } = await supabase
    .from('profiles')
    .update({
      subscription_id: subscription.id,
      subscription_status: subscription.status,
      subscription_tier: subscription.items.data[0]?.price?.lookup_key || null,
      current_period_start: new Date(subscription.current_period_start * 1000).toISOString(),
      current_period_end: new Date(subscription.current_period_end * 1000).toISOString(),
      last_webhook_event: event.id,
      sync_status: 'synced',
      updated_at: new Date().toISOString(),
    })
    .eq('stripe_customer_id', subscription.customer as string)

  if (error) {
    console.error('Database update error:', error)
    throw error
  }
  
  // Real-time update will be automatically triggered by the database change
  console.log(`Subscription ${subscription.id} updated for customer ${subscription.customer}`)
}

Connection State Management

Real-time connections can drop due to network issues or server restarts. Implement connection state management to handle these scenarios gracefully:

// components/SubscriptionStatusBadge.tsx
import { useRealtimeSubscription } from '@/hooks/useRealtimeSubscription'
import { useUser } from '@/hooks/useUser' // Your auth hook

export function SubscriptionStatusBadge() {
  const { user } = useUser()
  const { subscriptionState, isConnected } = useRealtimeSubscription(user)

  if (!subscriptionState) {
    return <div className=\"animate-pulse bg-gray-200 rounded px-2 py-1\">Loading...</div>
  }

  return (
    <div className=\"flex items-center space-x-2\">
      <span className={`px-3 py-1 rounded text-sm font-medium ${
        subscriptionState.subscription_status === 'active' 
          ? 'bg-green-100 text-green-800' 
          : 'bg-gray-100 text-gray-800'
      }`}>
        {subscriptionState.subscription_status}
      </span>
      
      {/* Real-time connection indicator */}
      <div className={`w-2 h-2 rounded-full ${
        isConnected ? 'bg-green-500' : 'bg-red-500'
      }`} title={isConnected ? 'Real-time connected' : 'Real-time disconnected'} />
      
      {subscriptionState.sync_status === 'pending' && (
        <span className=\"text-xs text-yellow-600\">Syncing...</span>
      )}
    </div>
  )
}

Performance and Scaling Considerations

Real-time subscriptions consume WebSocket connections and server resources. Here are key considerations for production deployment:

Connection Management:

• Each browser tab creates a separate WebSocket connection
• Supabase has connection limits per project (500 concurrent connections on Pro tier - sounds like a lot until you have actual users)
• Implement connection pooling for high-traffic applications

Real-time Policy Optimization:

• Use specific table filters (filter: 'id=eq.${user.id}') to reduce unnecessary data transfer
• Avoid subscribing to entire tables - target specific user data
• Consider using Supabase Edge Functions for complex real-time logic

Webhook Reliability:

• Implement idempotency handling for duplicate webhook events
• Add retry logic for failed database updates
• Monitor webhook processing latency - target under 30 seconds to avoid Stripe retries

Get this working and support stops asking why payments "don't work." Fuck it up and you'll explain the same shit every weekend.

The goal isn't perfect real-time sync (impossible). It's stopping users from panicking when their credit card gets charged but their dashboard still shows "Free Plan."

Next up: the actual implementation, including all the ways this breaks in production and how to fix it without losing your mind.

Every tutorial shows you the happy path - webhook comes in, database updates, users see changes instantly. Reality? Webhooks fail silently, RLS policies block updates, connections drop randomly, and users email support thinking their payment didn't work. Check Stripe's webhook reliability guide and Supabase troubleshooting docs for the real story.

This is what actually happens when you build this in production and why you'll question your career choices.

Step-by-Step Implementation

Phase 1: Database Migration Hell

Adding subscription columns to an existing profiles table? I've fucked this up twice. Once on a Friday evening (never again), once during a demo to investors (career limiting).

First time: Forgot the IF NOT EXISTS clause and the migration failed halfway through. 2,000 users couldn't log in for 3 hours while I restored from backup.

Here's what actually works without destroying your weekend:

-- Migration script for existing installations
-- Run this in Supabase SQL Editor

-- Add new columns for real-time sync
ALTER TABLE public.profiles 
ADD COLUMN IF NOT EXISTS subscription_id TEXT,
ADD COLUMN IF NOT EXISTS subscription_tier TEXT,
ADD COLUMN IF NOT EXISTS current_period_start TIMESTAMPTZ,
ADD COLUMN IF NOT EXISTS current_period_end TIMESTAMPTZ,
ADD COLUMN IF NOT EXISTS last_webhook_event TEXT,
ADD COLUMN IF NOT EXISTS sync_status TEXT DEFAULT 'synced';

-- Create index for efficient real-time filtering
CREATE INDEX IF NOT EXISTS idx_profiles_stripe_customer 
ON public.profiles(stripe_customer_id) 
WHERE stripe_customer_id IS NOT NULL;

-- Enable real-time replication for the profiles table
ALTER PUBLICATION supabase_realtime ADD TABLE public.profiles;

-- Create a function to update sync timestamps
CREATE OR REPLACE FUNCTION update_profile_sync_timestamp()
RETURNS TRIGGER AS $$
BEGIN
    NEW.updated_at = timezone('utc'::text, now());
    RETURN NEW;
END;
$$ language plpgsql;

-- Apply timestamp trigger
DROP TRIGGER IF EXISTS update_profiles_timestamp ON public.profiles;
CREATE TRIGGER update_profiles_timestamp
    BEFORE UPDATE ON public.profiles
    FOR EACH ROW
    EXECUTE FUNCTION update_profile_sync_timestamp();

Phase 2: Enhanced Authentication Context

Your auth context needs to handle real-time subscriptions without turning into spaghetti code. I learned this when my context re-rendered 47 times per subscription update and killed the browser.

// contexts/AuthContext.tsx
'use client'

import { createContext, useContext, useEffect, useState } from 'react'
import { User, Session } from '@supabase/supabase-js'
import { createClient } from '@/lib/supabase/client'

interface SubscriptionData {
  subscription_status: string
  subscription_tier: string | null
  current_period_end: string | null
  sync_status: 'synced' | 'pending' | 'error'
}

interface AuthContextType {
  user: User | null
  session: Session | null
  subscription: SubscriptionData | null
  isLoading: boolean
  isConnected: boolean
  signOut: () => Promise<void>
}

const AuthContext = createContext<AuthContextType | undefined>(undefined)

export function AuthProvider({ children }: { children: React.ReactNode }) {
  const [user, setUser] = useState<User | null>(null)
  const [session, setSession] = useState<Session | null>(null)
  const [subscription, setSubscription] = useState<SubscriptionData | null>(null)
  const [isLoading, setIsLoading] = useState(true)
  const [isConnected, setIsConnected] = useState(false)

  const supabase = createClient()

  useEffect(() => {
    // Get initial session
    const getSession = async () => {
      const { data: { session } } = await supabase.auth.getSession()
      setSession(session)
      setUser(session?.user ?? null)
      
      if (session?.user) {
        await fetchSubscriptionData(session.user.id)
        setupRealtimeSubscription(session.user.id)
      }
      
      setIsLoading(false)
    }

    getSession()

    // Listen for auth changes
    const { data: { subscription } } = supabase.auth.onAuthStateChange(
      async (event, session) => {
        setSession(session)
        setUser(session?.user ?? null)
        
        if (session?.user) {
          await fetchSubscriptionData(session.user.id)
          setupRealtimeSubscription(session.user.id)
        } else {
          setSubscription(null)
          setIsConnected(false)
        }
      }
    )

    return () => subscription.unsubscribe()
  }, [])

  const fetchSubscriptionData = async (userId: string) => {
    try {
      const { data, error } = await supabase
        .from('profiles')
        .select('subscription_status, subscription_tier, current_period_end, sync_status')
        .eq('id', userId)
        .single()

      if (error) {
        console.error('Error fetching subscription data:', error)
        return
      }

      setSubscription(data)
    } catch (error) {
      console.error('Subscription fetch error:', error)
    }
  }

  const setupRealtimeSubscription = (userId: string) => {
    const channel = supabase
      .channel(`profile-${userId}`)
      .on(
        'postgres_changes',
        {
          event: 'UPDATE',
          schema: 'public',
          table: 'profiles',
          filter: `id=eq.${userId}`,
        },
        (payload) => {
          console.log('Real-time subscription update:', payload.new)
          setSubscription(payload.new as SubscriptionData)
        }
      )
      .subscribe((status) => {
        setIsConnected(status === 'SUBSCRIBED')
        console.log('Real-time connection status:', status)
      })

    // Cleanup function will be handled by auth state change
    return () => supabase.removeChannel(channel)
  }

  const signOut = async () => {
    await supabase.auth.signOut()
    setSubscription(null)
    setIsConnected(false)
  }

  return (
    <AuthContext.Provider value={{
      user,
      session,
      subscription,
      isLoading,
      isConnected,
      signOut,
    }}>
      {children}
    </AuthContext.Provider>
  )
}

export const useAuth = () => {
  const context = useContext(AuthContext)
  if (context === undefined) {
    throw new Error('useAuth must be used within an AuthProvider')
  }
  return context
}

Phase 3: Production-Ready Webhook Handler

Your webhook handler will break in ways you never imagined. I've seen webhooks fail because someone changed a single character in an environment variable. I've seen them timeout because the database was busy. I've debugged for 6 hours only to find Stripe was sending malformed JSON (that was fun).

// app/api/webhooks/stripe/route.ts
import { headers } from 'next/headers'
import { NextRequest, NextResponse } from 'next/server'
import Stripe from 'stripe'
import { createClient } from '@/lib/supabase/server'

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: '2024-04-10' // Use latest stable - check Stripe docs before updating
  // Pro tip: Test the shit out of any API version changes in staging first
})

// Webhook timeout - Vercel kills requests at 30s, Stripe retries if you take >30s
// This causes webhook storms where Stripe thinks you're down and sends 
// the same event 50 times. Been there, done that, got the incident report.
const WEBHOOK_TIMEOUT = 25000 // 25 seconds because I learned the hard way that 30+ seconds triggers Stripe's retry storm

export async function POST(req: NextRequest) {
  const startTime = Date.now()
  const body = await req.text()
  const signature = headers().get('stripe-signature')!
  
  let event: Stripe.Event

  try {
    event = stripe.webhooks.constructEvent(
      body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET!
    )
  } catch (err) {
    // This fails for the stupidest reasons:
    // - Wrong webhook secret (I've done this 4 times)
    // - Stripe CLI forwarding breaks signatures in weird ways
    // - Vercel's body parsing sometimes corrupts raw body data
    // - Copy/paste errors when setting up webhook endpoints
    // - Most webhook signature failures = you copy/pasted the wrong secret. I've done this 6 times.
    const error = err instanceof Error ? err.message : 'Unknown error'
    console.error('Webhook signature verification failed:', {
      error,
      signature: signature?.substring(0, 20) + '...',
      bodyLength: body.length,
      // Most webhook failures = wrong secret. I keep this check because I'm an idiot:
      isWrongSecret: error.includes('No signatures found matching the expected signature')
    })
    return NextResponse.json({ error: 'Invalid signature' }, { status: 400 })
  }

  // Create timeout promise
  const timeoutPromise = new Promise((_, reject) => {
    setTimeout(() => reject(new Error('Webhook processing timeout')), WEBHOOK_TIMEOUT)
  })

  try {
    await Promise.race([
      processWebhookEvent(event),
      timeoutPromise
    ])

    const processingTime = Date.now() - startTime
    console.log(`Webhook ${event.type} processed successfully in ${processingTime}ms`)
    
    return NextResponse.json({ 
      received: true,
      event_id: event.id,
      processing_time: processingTime
    })
  } catch (error) {
    const processingTime = Date.now() - startTime
    console.error('Webhook processing failed:', {
      event_id: event.id,
      event_type: event.type,
      error: error instanceof Error ? error.message : 'Unknown error',
      processing_time: processingTime
    })
    
    return NextResponse.json(
      { 
        error: 'Webhook processing failed',
        event_id: event.id,
        retry_after: 60 // Tell Stripe to retry after 60 seconds
      },
      { status: 500 }
    )
  }
}

async function processWebhookEvent(event: Stripe.Event) {
  const supabase = createClient()

  // Check for duplicate event processing
  const { data: existingEvent } = await supabase
    .from('profiles')
    .select('last_webhook_event')
    .eq('last_webhook_event', event.id)
    .limit(1)

  if (existingEvent && existingEvent.length > 0) {
    console.log(`Duplicate webhook event ${event.id} - skipping processing`)
    return
  }

  switch (event.type) {
    case 'customer.subscription.created':
    case 'customer.subscription.updated':
      await handleSubscriptionChange(supabase, event)
      break
    
    case 'customer.subscription.deleted':
      await handleSubscriptionCancellation(supabase, event)
      break
      
    case 'invoice.payment_succeeded':
      await handleSuccessfulPayment(supabase, event)
      break
      
    case 'invoice.payment_failed':
      await handleFailedPayment(supabase, event)
      break
      
    default:
      console.log(`Unhandled webhook event: ${event.type}`)
  }
}

async function handleSubscriptionChange(supabase: any, event: Stripe.Event) {
  const subscription = event.data.object as Stripe.Subscription
  
  // Extract subscription tier from price lookup key or metadata
  const priceId = subscription.items.data[0]?.price?.id
  const lookupKey = subscription.items.data[0]?.price?.lookup_key
  
  // Determine subscription tier (customize based on your pricing model)
  let tier = 'basic'
  if (lookupKey?.includes('pro')) tier = 'pro'
  else if (lookupKey?.includes('enterprise')) tier = 'enterprise'

  const updateData = {
    subscription_id: subscription.id,
    subscription_status: subscription.status,
    subscription_tier: tier,
    current_period_start: new Date(subscription.current_period_start * 1000).toISOString(),
    current_period_end: new Date(subscription.current_period_end * 1000).toISOString(),
    last_webhook_event: event.id,
    sync_status: 'synced',
    updated_at: new Date().toISOString(),
  }

  const { error } = await supabase
    .from('profiles')
    .update(updateData)
    .eq('stripe_customer_id', subscription.customer as string)

  if (error) {
    console.error('Database update failed:', {
      error: error.message,
      customer_id: subscription.customer,
      subscription_id: subscription.id
    })
    throw error
  }

  console.log(`Subscription ${subscription.status} updated for customer ${subscription.customer}`)
}

async function handleSubscriptionCancellation(supabase: any, event: Stripe.Event) {
  const subscription = event.data.object as Stripe.Subscription

  const { error } = await supabase
    .from('profiles')
    .update({
      subscription_status: 'canceled',
      last_webhook_event: event.id,
      sync_status: 'synced',
      updated_at: new Date().toISOString(),
    })
    .eq('stripe_customer_id', subscription.customer as string)

  if (error) {
    console.error('Cancellation update failed:', error)
    throw error
  }
}

async function handleFailedPayment(supabase: any, event: Stripe.Event) {
  const invoice = event.data.object as Stripe.Invoice

  const { error } = await supabase
    .from('profiles')
    .update({
      subscription_status: 'past_due',
      last_webhook_event: event.id,
      sync_status: 'synced',
      updated_at: new Date().toISOString(),
    })
    .eq('stripe_customer_id', invoice.customer as string)

  if (error) {
    console.error('Failed payment update error:', error)
    throw error
  }
}

Phase 4: Real-time UI Components

Create reusable components that respond to real-time subscription changes:

// components/SubscriptionBanner.tsx
'use client'

import { useAuth } from '@/contexts/AuthContext'
import { useState, useEffect } from 'react'

export function SubscriptionBanner() {
  const { subscription, isConnected } = useAuth()
  const [showBanner, setShowBanner] = useState(false)
  const [lastStatus, setLastStatus] = useState<string | null>(null)

  useEffect(() => {
    // Show banner when subscription status changes
    if (subscription && lastStatus && subscription.subscription_status !== lastStatus) {
      setShowBanner(true)
      // Auto-hide banner after 5 seconds
      setTimeout(() => setShowBanner(false), 5000)
    }
    setLastStatus(subscription?.subscription_status || null)
  }, [subscription?.subscription_status])

  if (!subscription || subscription.subscription_status === 'active') {
    return null
  }

  if (subscription.sync_status === 'pending') {
    return (
      <div className="bg-yellow-50 border-l-4 border-yellow-400 p-4">
        <div className="flex">
          <div className="ml-3">
            <p className="text-sm text-yellow-700">
              Updating subscription status...
              {!isConnected && ' (Reconnecting to real-time updates)'}
            </p>
          </div>
        </div>
      </div>
    )
  }

  const getBannerConfig = (status: string) => {
    switch (status) {
      case 'past_due':
        return {
          bgColor: 'bg-red-50',
          borderColor: 'border-red-400',
          textColor: 'text-red-700',
          message: 'Payment failed. Please update your payment method to continue using our service.'
        }
      case 'canceled':
        return {
          bgColor: 'bg-gray-50',
          borderColor: 'border-gray-400',
          textColor: 'text-gray-700',
          message: 'Your subscription has been canceled. Reactivate anytime to regain access.'
        }
      case 'incomplete':
        return {
          bgColor: 'bg-yellow-50',
          borderColor: 'border-yellow-400',
          textColor: 'text-yellow-700',
          message: 'Payment verification required. Please complete your payment to activate your subscription.'
        }
      default:
        return {
          bgColor: 'bg-blue-50',
          borderColor: 'border-blue-400',
          textColor: 'text-blue-700',
          message: 'Subscription status updated.'
        }
    }
  }

  const config = getBannerConfig(subscription.subscription_status)

  return (
    <div className={`${config.bgColor} border-l-4 ${config.borderColor} p-4 ${showBanner ? 'animate-pulse' : ''}`}>
      <div className="flex justify-between items-center">
        <div className="flex">
          <div className="ml-3">
            <p className={`text-sm ${config.textColor}`}>
              {config.message}
            </p>
            {subscription.current_period_end && (
              <p className={`text-xs ${config.textColor} mt-1`}>
                Current period ends: ${new Date(subscription.current_period_end).toLocaleDateString()}
              </p>
            )}
          </div>
        </div>
        {!isConnected && (
          <div className="ml-4 flex-shrink-0">
            <span className="inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium bg-red-100 text-red-800">
              Offline
            </span>
          </div>
        )}
      </div>
    </div>
  )
}

Phase 5: Error Recovery and Retry Logic

Error recovery patterns must handle both webhook failures and real-time connection drops gracefully.

Implement robust error recovery for both webhook processing and real-time connection failures:

// lib/subscription-sync.ts
import { createClient } from '@/lib/supabase/client'

interface SyncResult {
  success: boolean
  error?: string
  retryAfter?: number
}

export class SubscriptionSyncManager {
  private supabase = createClient()
  private retryAttempts = new Map<string, number>()
  private maxRetries = 3

  async syncSubscriptionFromStripe(customerId: string): Promise<SyncResult> {
    const attemptKey = `sync-${customerId}`
    const attempts = this.retryAttempts.get(attemptKey) || 0

    if (attempts >= this.maxRetries) {
      return {
        success: false,
        error: 'Max retry attempts exceeded',
        retryAfter: 300 // 5 minutes
      }
    }

    try {
      // Mark sync as pending
      await this.supabase
        .from('profiles')
        .update({ sync_status: 'pending' })
        .eq('stripe_customer_id', customerId)

      // Trigger webhook replay via Stripe API if needed
      // This is a fallback for when webhooks fail
      const response = await fetch('/api/internal/sync-subscription', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ customerId })
      })

      if (!response.ok) {
        throw new Error(`Sync request failed: ${response.statusText}`)
      }

      this.retryAttempts.delete(attemptKey)
      return { success: true }

    } catch (error) {
      this.retryAttempts.set(attemptKey, attempts + 1)
      
      return {
        success: false,
        error: error instanceof Error ? error.message : 'Unknown sync error',
        retryAfter: Math.pow(2, attempts) * 30 // Exponential backoff: 30s, 60s, 120s
      }
    }
  }

  async handleConnectionDrop(userId: string) {
    // Fetch latest subscription state when reconnecting
    const { data, error } = await this.supabase
      .from('profiles')
      .select('subscription_status, subscription_tier, current_period_end, sync_status')
      .eq('id', userId)
      .single()

    if (error) {
      console.error('Failed to fetch subscription state after reconnection:', error)
      return null
    }

    return data
  }
}

// Hook for using the sync manager
export function useSubscriptionSync() {
  const [syncManager] = useState(() => new SubscriptionSyncManager())
  
  return {
    forcSync: syncManager.syncSubscriptionFromStripe.bind(syncManager),
    handleReconnection: syncManager.handleConnectionDrop.bind(syncManager)
  }
}

This implementation handles the most common failure modes without turning you into a 24/7 support robot. Users see changes when they should, webhooks don't silently fail, and connection drops recover gracefully.

Will it prevent all issues? Hell no. But you'll sleep better at night.

Reality check: Even with this setup, things will still break. WebSocket connections drop randomly. Stripe webhooks fail for mysterious reasons. Users will find edge cases you never imagined.

But at least you'll know why things broke and how to fix them quickly.