A card fails on Stripe,
your customer gets a WhatsApp.

# .env.local (server only, never NEXT_PUBLIC_)
STRIPE_SECRET_KEY=sk_test_xxxx
# Printed by "stripe listen" in dev, or shown on the endpoint in the Dashboard
STRIPE_WEBHOOK_SECRET=whsec_xxxx
UM_API_KEY=um_live_xxxx

// lib/notify.ts
import 'server-only';

export type Channel = 'EMAIL' | 'WHATSAPP' | 'SMS';

export async function notify(input: {
  email?: string;
  phone?: string; // E.164, e.g. +33612345678
  channels: Channel[];
  subject: string;
  text: string;
}) {
  const channels = input.channels
    .filter((c) => (c === 'EMAIL' ? input.email : input.phone))
    .map((channel) => ({ channel }));
  if (channels.length === 0) return null;

  const res = await fetch('https://api.unlimitedmessaging.app/message', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.UM_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      to: { email: input.email, phone: input.phone },
      channels,
      subject: input.subject,
      text: input.text,
      priority: 'transactional',
    }),
  });
  if (!res.ok) throw new Error(`Unlimited Messaging ${res.status}: ${await res.text()}`);
  return res.json();
}

// app/api/stripe/webhook/route.ts
import type Stripe from 'stripe';
import { after } from 'next/server';
import { stripe, handleStripeEvent } from '@/lib/stripe-notify';

export async function POST(req: Request) {
  // The raw body: parsing it as JSON first breaks the signature check
  const body = await req.text();
  const signature = req.headers.get('stripe-signature') ?? '';

  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(body, signature, process.env.STRIPE_WEBHOOK_SECRET!);
  } catch {
    return new Response('Invalid signature', { status: 400 });
  }

  // Answer Stripe with a 2xx right away, send the messages after the response
  after(() => handleStripeEvent(event).catch(console.error));
  return new Response('ok', { status: 200 });
}

// lib/stripe-notify.ts
import 'server-only';
import Stripe from 'stripe';
import { notify, type Channel } from '@/lib/notify';

export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

const money = (amount: number, currency: string) =>
  new Intl.NumberFormat('en', { style: 'currency', currency }).format(amount / 100);

export async function handleStripeEvent(event: Stripe.Event) {
  // Stripe can send the same event twice: skip the ones already handled
  if (!(await markProcessed(event.id))) return;

  switch (event.type) {
    case 'invoice.paid': {
      const inv = event.data.object;
      await notify({
        email: inv.customer_email ?? undefined,
        channels: ['EMAIL'],
        subject: 'Payment received',
        text: `Thanks, we received ${money(inv.amount_paid, inv.currency)}.`,
      });
      break;
    }
    case 'invoice.payment_failed': {
      const inv = event.data.object;
      // First failure: email + WhatsApp. Next retries: SMS as well.
      const channels: Channel[] =
        inv.attempt_count > 1 ? ['EMAIL', 'WHATSAPP', 'SMS'] : ['EMAIL', 'WHATSAPP'];
      await notify({
        email: inv.customer_email ?? undefined,
        phone: inv.customer_phone ?? undefined,
        channels,
        subject: 'Your payment did not go through',
        text: `Your payment of ${money(inv.amount_due, inv.currency)} failed. Update your card here: ${inv.hosted_invoice_url}`,
      });
      break;
    }
    case 'customer.subscription.trial_will_end': {
      const sub = event.data.object; // sent 3 days before the trial ends
      const customer = await stripe.customers.retrieve(sub.customer as string);
      if (customer.deleted) break;
      await notify({
        email: customer.email ?? undefined,
        phone: customer.phone ?? undefined,
        channels: ['EMAIL', 'WHATSAPP'],
        subject: 'Your trial ends in 3 days',
        text: 'Your trial ends in 3 days. Nothing to do if your card is up to date.',
      });
      break;
    }
  }
}

async function markProcessed(eventId: string): Promise<boolean> {
  // e.g. INSERT INTO stripe_events (id) VALUES ($1) ON CONFLICT DO NOTHING,
  // then return true only when a row was inserted
  return true;
}

# Forward test events to your local route (prints a whsec_ secret)
stripe listen --forward-to localhost:3000/api/stripe/webhook

# In another terminal: fire a failed payment
stripe trigger invoice.payment_failed