How to Send Emails from Paddle Webhooks (2026 Guide)

npm install sequenzy

npm install resend

npm install @sendgrid/mail

SEQUENZY_API_KEY=sq_your_api_key_here

RESEND_API_KEY=re_your_api_key_here

SENDGRID_API_KEY=SG.your_api_key_here

import Sequenzy from "sequenzy";

// Reads SEQUENZY_API_KEY from env automatically
export const sequenzy = new Sequenzy();

import { Resend } from "resend";

export const resend = new Resend(process.env.RESEND_API_KEY);
export const FROM = "Your App <noreply@yourdomain.com>";

import sgMail from "@sendgrid/mail";

sgMail.setApiKey(process.env.SENDGRID_API_KEY!);
export { sgMail };
export const FROM = "noreply@yourdomain.com";

import { NextRequest, NextResponse } from "next/server";
import { sequenzy } from "@/lib/email";
import { verifyPaddleWebhook, isTimestampValid } from "@/lib/paddle";
import {
welcomeEmail,
paymentConfirmationEmail,
paymentFailedEmail,
trialStartedEmail,
cancellationEmail,
planChangeEmail,
pausedEmail,
resumedEmail,
} from "@/lib/paddle-emails";

const APP_URL = process.env.APP_URL!;

export async function POST(request: NextRequest) {
const body = await request.text();
const signature = request.headers.get("paddle-signature") ?? "";

if (!isTimestampValid(signature)) {
  return NextResponse.json({ error: "Stale webhook" }, { status: 400 });
}

if (!verifyPaddleWebhook(body, signature, process.env.PADDLE_WEBHOOK_SECRET!)) {
  return NextResponse.json({ error: "Invalid signature" }, { status: 400 });
}

const event = JSON.parse(body);

try {
  await handlePaddleEvent(event);
} catch (error) {
  console.error(`Paddle webhook failed for ${event.event_type}:`, error);
}

return NextResponse.json({ received: true });
}

interface PaddleEvent {
event_type: string;
notification_id: string;
data: Record<string, unknown>;
}

async function handlePaddleEvent(event: PaddleEvent) {
const data = event.data;

switch (event.event_type) {
  case "subscription.created": {
    const email = getCustomerEmail(data);
    if (!email) break;

    // Check if this is a trial or paid subscription
    const status = data.status as string;

    if (status === "trialing") {
      const trialEnd = data.current_billing_period
        ? new Date((data.current_billing_period as { ends_at: string }).ends_at).toLocaleDateString()
        : "soon";

      await sequenzy.transactional.send({
        to: email,
        subject: "Your free trial has started!",
        body: trialStartedEmail({ trialEndDate: trialEnd, appUrl: APP_URL }),
      });
    } else {
      await sequenzy.transactional.send({
        to: email,
        subject: "Welcome! Your subscription is active",
        body: welcomeEmail(APP_URL),
      });
    }

    // Add as subscriber for marketing
    await sequenzy.subscribers.create({
      email,
      tags: [status === "trialing" ? "trial" : "customer", "paddle"],
      customAttributes: {
        paddleSubscriptionId: data.id as string,
        plan: getProductName(data),
      },
    });
    break;
  }

  case "transaction.completed": {
    const email = getCustomerEmail(data);
    if (!email) break;

    // Get the transaction totals
    const details = data.details as { totals: { total: string } } | undefined;
    const currencyCode = data.currency_code as string;
    const total = details?.totals?.total ?? "0";

    // Format the amount (Paddle sends amounts as strings, not cents)
    const formatted = formatPaddleAmount(total, currencyCode);

    await sequenzy.transactional.send({
      to: email,
      subject: `Payment confirmed - ${formatted}`,
      body: paymentConfirmationEmail({
        amount: total,
        currency: currencyCode,
        productName: getProductName(data),
        appUrl: APP_URL,
      }),
    });
    break;
  }

  case "subscription.past_due": {
    const email = getCustomerEmail(data);
    if (!email) break;

    // Paddle provides a management URL for updating payment methods
    const managementUrls = data.management_urls as {
      update_payment_method?: string;
    } | undefined;

    const updateUrl = managementUrls?.update_payment_method
      ?? `${APP_URL}/billing`;

    await sequenzy.transactional.send({
      to: email,
      subject: "Payment failed - action required",
      body: paymentFailedEmail({ updateUrl, appUrl: APP_URL }),
    });

    // Update subscriber tags
    await sequenzy.subscribers.tags.add({
      email,
      tag: "past-due",
    });
    break;
  }

  case "subscription.updated": {
    const email = getCustomerEmail(data);
    if (!email) break;

    const status = data.status as string;
    const scheduledChange = data.scheduled_change as {
      action: string;
      effective_at: string;
    } | null;

    // Handle pause
    if (status === "paused" || scheduledChange?.action === "pause") {
      const resumeDate = scheduledChange?.effective_at
        ? new Date(scheduledChange.effective_at).toLocaleDateString()
        : "your next billing date";

      await sequenzy.transactional.send({
        to: email,
        subject: "Your subscription has been paused",
        body: pausedEmail({ resumeDate, appUrl: APP_URL }),
      });
      break;
    }

    // Handle resume
    if (status === "active" && data.paused_at) {
      await sequenzy.transactional.send({
        to: email,
        subject: "Welcome back! Subscription resumed",
        body: resumedEmail(APP_URL),
      });
      break;
    }

    // Handle plan change
    const items = data.items as Array<{
      price: { unit_price: { amount: string; currency_code: string }; description: string };
      product: { name: string };
    }> | undefined;

    if (items && items.length > 0) {
      const item = items[0];
      const price = item.price.unit_price;

      await sequenzy.transactional.send({
        to: email,
        subject: `Plan updated to ${item.product.name}`,
        body: planChangeEmail({
          newPlan: item.product.name,
          newAmount: formatPaddleAmount(price.amount, price.currency_code),
          currency: price.currency_code,
          effectiveDate: new Date().toLocaleDateString(),
          appUrl: APP_URL,
        }),
      });
    }
    break;
  }

  case "subscription.canceled": {
    const email = getCustomerEmail(data);
    if (!email) break;

    const currentPeriod = data.current_billing_period as {
      ends_at: string;
    } | undefined;
    const endDate = currentPeriod?.ends_at
      ? new Date(currentPeriod.ends_at).toLocaleDateString()
      : "the end of your billing period";

    await sequenzy.transactional.send({
      to: email,
      subject: "Your subscription has been cancelled",
      body: cancellationEmail({
        endDate,
        pricingUrl: `${APP_URL}/pricing`,
      }),
    });

    await sequenzy.subscribers.tags.add({
      email,
      tag: "cancelled",
    });
    break;
  }
}
}

// --- Helper functions ---

function getCustomerEmail(data: Record<string, unknown>): string | null {
// Paddle nests customer data differently per event type
const customer = data.customer as { email?: string } | undefined;
if (customer?.email) return customer.email;

// Some events have customer_id but not email - you'd need to look it up
return null;
}

function getProductName(data: Record<string, unknown>): string {
const items = data.items as Array<{
  product?: { name?: string };
  price?: { description?: string };
}> | undefined;

return items?.[0]?.product?.name
  ?? items?.[0]?.price?.description
  ?? "Subscription";
}

function formatPaddleAmount(amount: string, currency: string): string {
// Paddle sends amounts as strings like "4900" for $49.00
const num = parseInt(amount, 10);
if (isNaN(num)) return `${amount} ${currency}`;
return `${(num / 100).toFixed(2)} ${currency}`;
}

import { NextRequest, NextResponse } from "next/server";
import { resend, FROM } from "@/lib/email";
import { verifyPaddleWebhook, isTimestampValid } from "@/lib/paddle";
import {
welcomeEmail,
paymentConfirmationEmail,
paymentFailedEmail,
trialStartedEmail,
cancellationEmail,
planChangeEmail,
pausedEmail,
resumedEmail,
} from "@/lib/paddle-emails";

const APP_URL = process.env.APP_URL!;

export async function POST(request: NextRequest) {
const body = await request.text();
const signature = request.headers.get("paddle-signature") ?? "";

if (!isTimestampValid(signature)) {
  return NextResponse.json({ error: "Stale webhook" }, { status: 400 });
}

if (!verifyPaddleWebhook(body, signature, process.env.PADDLE_WEBHOOK_SECRET!)) {
  return NextResponse.json({ error: "Invalid signature" }, { status: 400 });
}

const event = JSON.parse(body);

try {
  await handlePaddleEvent(event);
} catch (error) {
  console.error(`Paddle webhook failed for ${event.event_type}:`, error);
}

return NextResponse.json({ received: true });
}

interface PaddleEvent {
event_type: string;
notification_id: string;
data: Record<string, unknown>;
}

async function handlePaddleEvent(event: PaddleEvent) {
const data = event.data;

switch (event.event_type) {
  case "subscription.created": {
    const email = getCustomerEmail(data);
    if (!email) break;

    const status = data.status as string;

    if (status === "trialing") {
      const trialEnd = data.current_billing_period
        ? new Date((data.current_billing_period as { ends_at: string }).ends_at).toLocaleDateString()
        : "soon";

      await resend.emails.send({
        from: FROM, to: email,
        subject: "Your free trial has started!",
        html: trialStartedEmail({ trialEndDate: trialEnd, appUrl: APP_URL }),
      });
    } else {
      await resend.emails.send({
        from: FROM, to: email,
        subject: "Welcome! Your subscription is active",
        html: welcomeEmail(APP_URL),
      });
    }
    break;
  }

  case "transaction.completed": {
    const email = getCustomerEmail(data);
    if (!email) break;

    const details = data.details as { totals: { total: string } } | undefined;
    const currencyCode = data.currency_code as string;
    const total = details?.totals?.total ?? "0";

    await resend.emails.send({
      from: FROM, to: email,
      subject: `Payment confirmed - ${formatPaddleAmount(total, currencyCode)}`,
      html: paymentConfirmationEmail({
        amount: total, currency: currencyCode,
        productName: getProductName(data), appUrl: APP_URL,
      }),
    });
    break;
  }

  case "subscription.past_due": {
    const email = getCustomerEmail(data);
    if (!email) break;

    const managementUrls = data.management_urls as {
      update_payment_method?: string;
    } | undefined;

    await resend.emails.send({
      from: FROM, to: email,
      subject: "Payment failed - action required",
      html: paymentFailedEmail({
        updateUrl: managementUrls?.update_payment_method ?? `${APP_URL}/billing`,
        appUrl: APP_URL,
      }),
    });
    break;
  }

  case "subscription.updated": {
    const email = getCustomerEmail(data);
    if (!email) break;

    const status = data.status as string;
    const scheduledChange = data.scheduled_change as {
      action: string; effective_at: string;
    } | null;

    if (status === "paused" || scheduledChange?.action === "pause") {
      await resend.emails.send({
        from: FROM, to: email,
        subject: "Your subscription has been paused",
        html: pausedEmail({
          resumeDate: scheduledChange?.effective_at
            ? new Date(scheduledChange.effective_at).toLocaleDateString()
            : "your next billing date",
          appUrl: APP_URL,
        }),
      });
      break;
    }

    if (status === "active" && data.paused_at) {
      await resend.emails.send({
        from: FROM, to: email,
        subject: "Welcome back! Subscription resumed",
        html: resumedEmail(APP_URL),
      });
      break;
    }

    const items = data.items as Array<{
      price: { unit_price: { amount: string; currency_code: string } };
      product: { name: string };
    }> | undefined;

    if (items?.length) {
      const item = items[0];
      const price = item.price.unit_price;

      await resend.emails.send({
        from: FROM, to: email,
        subject: `Plan updated to ${item.product.name}`,
        html: planChangeEmail({
          newPlan: item.product.name,
          newAmount: formatPaddleAmount(price.amount, price.currency_code),
          currency: price.currency_code,
          effectiveDate: new Date().toLocaleDateString(),
          appUrl: APP_URL,
        }),
      });
    }
    break;
  }

  case "subscription.canceled": {
    const email = getCustomerEmail(data);
    if (!email) break;

    const currentPeriod = data.current_billing_period as {
      ends_at: string;
    } | undefined;

    await resend.emails.send({
      from: FROM, to: email,
      subject: "Your subscription has been cancelled",
      html: cancellationEmail({
        endDate: currentPeriod?.ends_at
          ? new Date(currentPeriod.ends_at).toLocaleDateString()
          : "the end of your billing period",
        pricingUrl: `${APP_URL}/pricing`,
      }),
    });
    break;
  }
}
}

function getCustomerEmail(data: Record<string, unknown>): string | null {
const customer = data.customer as { email?: string } | undefined;
return customer?.email ?? null;
}

function getProductName(data: Record<string, unknown>): string {
const items = data.items as Array<{
  product?: { name?: string }; price?: { description?: string };
}> | undefined;
return items?.[0]?.product?.name ?? items?.[0]?.price?.description ?? "Subscription";
}

function formatPaddleAmount(amount: string, currency: string): string {
const num = parseInt(amount, 10);
if (isNaN(num)) return `${amount} ${currency}`;
return `${(num / 100).toFixed(2)} ${currency}`;
}

import { NextRequest, NextResponse } from "next/server";
import { sgMail, FROM } from "@/lib/email";
import { verifyPaddleWebhook, isTimestampValid } from "@/lib/paddle";
import {
welcomeEmail,
paymentConfirmationEmail,
paymentFailedEmail,
trialStartedEmail,
cancellationEmail,
planChangeEmail,
pausedEmail,
resumedEmail,
} from "@/lib/paddle-emails";

const APP_URL = process.env.APP_URL!;

export async function POST(request: NextRequest) {
const body = await request.text();
const signature = request.headers.get("paddle-signature") ?? "";

if (!isTimestampValid(signature)) {
  return NextResponse.json({ error: "Stale webhook" }, { status: 400 });
}

if (!verifyPaddleWebhook(body, signature, process.env.PADDLE_WEBHOOK_SECRET!)) {
  return NextResponse.json({ error: "Invalid signature" }, { status: 400 });
}

const event = JSON.parse(body);

try {
  await handlePaddleEvent(event);
} catch (error) {
  console.error(`Paddle webhook failed for ${event.event_type}:`, error);
}

return NextResponse.json({ received: true });
}

interface PaddleEvent {
event_type: string;
notification_id: string;
data: Record<string, unknown>;
}

async function handlePaddleEvent(event: PaddleEvent) {
const data = event.data;

switch (event.event_type) {
  case "subscription.created": {
    const email = getCustomerEmail(data);
    if (!email) break;

    const status = data.status as string;

    if (status === "trialing") {
      const trialEnd = data.current_billing_period
        ? new Date((data.current_billing_period as { ends_at: string }).ends_at).toLocaleDateString()
        : "soon";

      await sgMail.send({
        to: email, from: FROM,
        subject: "Your free trial has started!",
        html: trialStartedEmail({ trialEndDate: trialEnd, appUrl: APP_URL }),
      });
    } else {
      await sgMail.send({
        to: email, from: FROM,
        subject: "Welcome! Your subscription is active",
        html: welcomeEmail(APP_URL),
      });
    }
    break;
  }

  case "transaction.completed": {
    const email = getCustomerEmail(data);
    if (!email) break;

    const details = data.details as { totals: { total: string } } | undefined;
    const currencyCode = data.currency_code as string;
    const total = details?.totals?.total ?? "0";

    await sgMail.send({
      to: email, from: FROM,
      subject: `Payment confirmed - ${formatPaddleAmount(total, currencyCode)}`,
      html: paymentConfirmationEmail({
        amount: total, currency: currencyCode,
        productName: getProductName(data), appUrl: APP_URL,
      }),
    });
    break;
  }

  case "subscription.past_due": {
    const email = getCustomerEmail(data);
    if (!email) break;

    const managementUrls = data.management_urls as {
      update_payment_method?: string;
    } | undefined;

    await sgMail.send({
      to: email, from: FROM,
      subject: "Payment failed - action required",
      html: paymentFailedEmail({
        updateUrl: managementUrls?.update_payment_method ?? `${APP_URL}/billing`,
        appUrl: APP_URL,
      }),
    });
    break;
  }

  case "subscription.updated": {
    const email = getCustomerEmail(data);
    if (!email) break;

    const status = data.status as string;
    const scheduledChange = data.scheduled_change as {
      action: string; effective_at: string;
    } | null;

    if (status === "paused" || scheduledChange?.action === "pause") {
      await sgMail.send({
        to: email, from: FROM,
        subject: "Your subscription has been paused",
        html: pausedEmail({
          resumeDate: scheduledChange?.effective_at
            ? new Date(scheduledChange.effective_at).toLocaleDateString()
            : "your next billing date",
          appUrl: APP_URL,
        }),
      });
      break;
    }

    if (status === "active" && data.paused_at) {
      await sgMail.send({
        to: email, from: FROM,
        subject: "Welcome back! Subscription resumed",
        html: resumedEmail(APP_URL),
      });
      break;
    }

    const items = data.items as Array<{
      price: { unit_price: { amount: string; currency_code: string } };
      product: { name: string };
    }> | undefined;

    if (items?.length) {
      const item = items[0];
      const price = item.price.unit_price;

      await sgMail.send({
        to: email, from: FROM,
        subject: `Plan updated to ${item.product.name}`,
        html: planChangeEmail({
          newPlan: item.product.name,
          newAmount: formatPaddleAmount(price.amount, price.currency_code),
          currency: price.currency_code,
          effectiveDate: new Date().toLocaleDateString(),
          appUrl: APP_URL,
        }),
      });
    }
    break;
  }

  case "subscription.canceled": {
    const email = getCustomerEmail(data);
    if (!email) break;

    const currentPeriod = data.current_billing_period as {
      ends_at: string;
    } | undefined;

    await sgMail.send({
      to: email, from: FROM,
      subject: "Your subscription has been cancelled",
      html: cancellationEmail({
        endDate: currentPeriod?.ends_at
          ? new Date(currentPeriod.ends_at).toLocaleDateString()
          : "the end of your billing period",
        pricingUrl: `${APP_URL}/pricing`,
      }),
    });
    break;
  }
}
}

function getCustomerEmail(data: Record<string, unknown>): string | null {
const customer = data.customer as { email?: string } | undefined;
return customer?.email ?? null;
}

function getProductName(data: Record<string, unknown>): string {
const items = data.items as Array<{
  product?: { name?: string }; price?: { description?: string };
}> | undefined;
return items?.[0]?.product?.name ?? items?.[0]?.price?.description ?? "Subscription";
}

function formatPaddleAmount(amount: string, currency: string): string {
const num = parseInt(amount, 10);
if (isNaN(num)) return `${amount} ${currency}`;
return `${(num / 100).toFixed(2)} ${currency}`;
}