Send emails from Stripe webhooks: events, signatures and a full Node example

// app/stripe/webhook/route.ts
import Stripe from "stripe";

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

export async function POST(request: Request) {
  const body = await request.text(); // raw body, not request.json()
  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(
      body,
      request.headers.get("stripe-signature")!,
      process.env.STRIPE_WEBHOOK_SECRET!,
    );
  } catch {
    return new Response("Bad signature", { status: 400 });
  }
  await handleStripeEvent(event); // the switch from the full example below
  return new Response(null, { status: 200 });
}

import express from "express";
import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
const app = express();

app.post("/stripe/webhook", express.raw({ type: "application/json" }), async (req, res) => {
  let event;
  try {
    event = stripe.webhooks.constructEvent(
      req.body,
      req.headers["stripe-signature"],
      process.env.STRIPE_WEBHOOK_SECRET,
    );
  } catch (err) {
    return res.status(400).send(`Webhook signature check failed: ${err.message}`);
  }

  // Seen this event before? Acknowledge it and do nothing.
  const fresh = await db.query(
    "INSERT INTO stripe_events (id) VALUES ($1) ON CONFLICT DO NOTHING RETURNING id",
    [event.id],
  );
  if (!fresh.rows[0]) return res.sendStatus(200);

  try {
    await handleStripeEvent(event);
  } catch (err) {
    console.error(err);
    await db.query("DELETE FROM stripe_events WHERE id = $1", [event.id]); // let the retry run
    return res.sendStatus(500);
  }
  res.sendStatus(200);
});

async function handleStripeEvent(event) {
  switch (event.type) {
    case "invoice.paid": {
      const invoice = event.data.object;
      if (invoice.amount_paid === 0 || !invoice.customer_email) return;
      const amount = money(invoice.amount_paid, invoice.currency);
      return sendEmail(`receipt:${invoice.id}`, {
        to: invoice.customer_email,
        subject: `Receipt for ${amount}, invoice ${invoice.number}`,
        html: `<p>We received ${amount}. Thank you.</p>
<p><a href="${invoice.hosted_invoice_url}">View invoice</a> · <a href="${invoice.invoice_pdf}">PDF</a></p>`,
      });
    }

    case "invoice.payment_failed": {
      const invoice = event.data.object;
      if (!invoice.customer_email) return;
      const amount = money(invoice.amount_due, invoice.currency);
      const retry = invoice.next_payment_attempt
        ? `We'll try again on ${new Date(invoice.next_payment_attempt * 1000).toDateString()}.`
        : "";
      return sendEmail(`payment-failed:${invoice.id}:${invoice.attempt_count}`, {
        to: invoice.customer_email,
        subject: "Your payment didn't go through",
        html: `<p>We couldn't take your payment of ${amount}. ${retry}</p>
<p><a href="${invoice.hosted_invoice_url}">Update your card and pay</a></p>`,
      });
    }

    case "customer.subscription.trial_will_end": {
      const sub = event.data.object;
      const customer = await stripe.customers.retrieve(sub.customer);
      if (customer.deleted || !customer.email) return;
      const ends = new Date(sub.trial_end * 1000).toDateString();
      return sendEmail(`trial-ending:${sub.id}`, {
        to: customer.email,
        subject: `Your trial ends on ${ends}`,
        html: `<p>Hi ${escapeHtml(customer.name ?? "there")}, your trial ends on ${ends}.</p>
<p><a href="https://app.example.com/billing">Choose a plan</a></p>`,
      });
    }

    case "checkout.session.expired": {
      const session = event.data.object;
      const email = session.customer_details?.email;
      const url = session.after_expiration?.recovery?.url;
      // Only people who agreed to promotional email, and only with a recovery link.
      if (!email || !url || session.consent?.promotions !== "opt_in") return;
      return sendEmail(`checkout-recovery:${email}`, {
        to: email,
        subject: "You left something in your cart",
        html: `<p>Your checkout is saved. <a href="${url}">Pick up where you left off</a>.</p>`,
        category: "product",
      });
    }
  }
}

async function sendEmail(key, { to, subject, html, category = "transactional" }) {
  const res = await fetch("https://api.groundmail.dev/emails", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.GROUNDMAIL_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": key,
    },
    body: JSON.stringify({
      from: "Example Billing <billing@mail.example.com>",
      to,
      subject,
      html,
      category,
    }),
  });
  // 409: this key already sent an email (with a different body). Treat it as sent.
  if (res.status === 409) return;
  if (!res.ok) throw new Error(`Groundmail ${res.status}: ${await res.text()}`);
}

function money(amount, currency) {
  // Stripe amounts are in the smallest unit; zero-decimal currencies (JPY, KRW) aren't divided.
  return new Intl.NumberFormat("en-US", { style: "currency", currency: currency.toUpperCase() })
    .format(amount / 100);
}

app.listen(3000);