OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add developer.paddle.com/paddle-webhooks
Receive and verify Paddle webhooks in a Next.js Route Handler — signature verification, idempotency, retry semantics, and local testing.
npx skills add developer.paddle.com/paddle-webhooks
Use this skill when building the server-side endpoint that receives Paddle webhook events (subscription changes, transactions, customer updates, payouts, etc.). It covers creating the notification destination in Paddle, writing a Next.js Route Handler that verifies signatures and processes events, handling retries and idempotency, and local testing.
This skill is the foundation for almost every server-side Paddle integration. Pair with:
subscription-sync — turn webhook events into rows in your database.sandbox-testing — drive your endpoint with the webhook simulator.checkout-web — the client-side counterpart that triggers the events you'll receive here.Every design choice in this skill follows from these facts about how Paddle delivers webhooks. Read this section first; everything else is mechanics.
2xx within 5 seconds is "delivered." Any other response — 400, 401, 500, 503, a redirect, a connection timeout — is treated as a failed delivery and gets retried. There is no status code that means "stop retrying" on the integrator side. Paddle retries any non-2xx response.attempt^1.1). Connection timeouts count toward the same budget as non-2xx responses.event.eventId on every retry. Paddle re-sends the identical payload (modulo a fresh signature timestamp) until you 2xx or the retry budget is exhausted. That id is your dedup key.301 or 302 is treated as a failed delivery, not followed.client.notifications.replay(notificationId) inside an execute call (note: notificationId is a positional path param, not a body field). Plan for this when bringing an endpoint back from extended downtime — query the API for current state rather than waiting for events.The Paddle MCP exposes three tools per server (
search,execute,report_missing_tool). Workflow: callsearchto confirm the exact method name and parameter shapes, then callexecutewith an async function that callsclient.<resource>.<operation>(...). Method paths are camelCase (client.clientTokens.create,client.pricingPreview.preview). Body params and response fields are snake_case (tax_category,product_id,unit_price,currency_code). Pagination is{ pagination: { hasMore }, data: [...] }with{ after: "<last_id>" }— not.next()/.hasMore. Chain multi-step workflows inside oneexecute; variables don't persist between calls. Hard caps: 50 API calls per execute, 30s timeout, 32KB code.
You need:
catalog-setup if you don't have one yet.Install the server SDK:
A notification destination tells Paddle "send these events to this URL." Each destination has its own secret — sandbox and production should be separate destinations with separate secrets, never shared.
client.notificationSettings.create({ destination: "https://...", subscribed_events: [...], type: "url" }) inside an execute to create the destination programmatically — skip the dashboard steps below. CamelCase resource, snake_case body. See conventions above.)Local dev (or Production).Webhook.https://your-app.com/api/webhook or your tunnelled local URL).transaction.completed, subscription.created, subscription.updated, subscription.canceled, customer.created, customer.updated. You can subscribe to more later.PADDLE_NOTIFICATION_WEBHOOK_SECRET.Create a single instance of the Node SDK so you don't initialize it on every request.
Two rules. Pre-validate inputs you can check cheaply (return 400). Wrap everything else in a single try/catch that returns a non-2xx on any throw — including signature failures — so Paddle retries. Any non-2xx works (this skill uses 500; 401 is equally valid); the only response that loses the event is a 2xx.
paddle.webhooks.unmarshal() does three things in one call:
paddle-signature header against the raw body using your secret.EventEntity with the deserialized payload.Why a single catch returning one non-2xx, even for signature failures? A thrown unmarshal doesn't tell you why it threw — a tampered request, a wrong/rotated secret, an expired timestamp, and a malformed event all surface as the same generic error. Every non-2xx is retried on the same budget, so 401 and 500 are equally event-safe: a rotated secret recovers automatically once you redeploy, whichever you pick. Don't try to split them (401 for "forged", 500 for "transient") — you can't tell those cases apart, so choose one non-2xx and use it for the whole catch. The only choice that loses events is returning 2xx on a failure.
Keep the route handler thin. Move event-specific logic into a separate function and switch on eventType using the EventName enum so TypeScript narrows event.data correctly:
The Node SDK exports EventName (the string discriminator) and a typed event for each — TypeScript narrows event.data correctly when you switch on eventType. String literal comparisons like event.eventType === "subscription.created" work at runtime but lose narrowing and are fragile to spec changes.
The default path: write handlers in an UPSERT shape keyed on the Paddle resource id. Then duplicate deliveries become idempotent for free, and you don't need any extra bookkeeping.
Most webhook work fits this shape — subscription state, customer records, transaction records all have stable Paddle ids you can key on. The official starter kit (paddle-nextjs-starter-kit, see src/utils/paddle/process-webhook.ts) uses supabase.from("subscriptions").upsert({...}) exactly this way and has no explicit dedup ledger.
Some side effects aren't naturally idempotent — sending a receipt email, granting one-time credits, calling a third-party API that bills per request. For those, dedupe explicitly on event.eventId:
The minimal table:
Use the ledger only when UPSERT-shaping doesn't cover the side effect. For most subscription/customer/transaction sync work, UPSERT is enough.
The 5-second timeout is real. If your handler takes longer, Paddle treats it as a connection timeout, marks the delivery as timed out, and counts the attempt against your retry budget.
Pattern:
event.eventId (or upsert the resource synchronously if it's cheap).paddle.transactions.list(), generating PDFs — onto a background queue.200.Concretely: don't run paddle.transactions.list() inline inside a webhook handler. Don't send an email inline. Don't call Stripe or any other third-party from inside the route handler. Verify, queue, ack.
If you don't have a queue yet, a Vercel Queue, AWS SQS, or even a simple "insert into a pending_jobs table and process from a cron" is enough.
Two patterns:
A. Tunnel a public URL to localhost. Use ngrok, cloudflared, or vercel dev --listen 0.0.0.0 then set up a tunnel.
Real Paddle events from the sandbox will then hit your local route handler.
B. Use the webhook simulator. No tunnel needed for the simulator's "single event" mode targeted at a public URL, but for local testing the easiest flow is:
subscription.created, transaction.paid).See sandbox-testing for the full sandbox + simulator workflow.
2xx on a failed verification. This is the one status mistake that loses events: Paddle considers only 2xx responses as delivered, so a 2xx on a failed unmarshal marks the event delivered and it's never retried. Every non-2xx — 400, 401, 500, 503 — is retried on the same budget, so returning 401 on a signature failure does not lose events (a rotated secret still gets the full retry window to recover). The only status that stops retries from the integrator side is 2xx. If you have actual abuse to fend off, do it at the edge with rate limits, not inside the handler.unmarshal throws indistinguishably for a tampered request, a wrong/rotated secret, an expired timestamp, and a malformed event, so the split is illusory — you can't actually tell which case you're in. Pick one non-2xx and use it for the whole catch. One catch, one status, one operational story.request.json(), then re-serialize to verify, the byte sequence won't match what Paddle signed. Always use await request.text() and pass the raw string to unmarshal().unmarshal throwing on every delivery. PADDLE_NOTIFICATION_WEBHOOK_SECRET must match the destination you're targeting — and is not the same value as PADDLE_API_KEY.subscription.updated can arrive before the corresponding subscription.created if the first delivery is being retried. Use occurred_at if you need ordering, but the cleanest approach is to make handlers convergent — UPSERT to latest state.bodyParser to access the raw body. App Router Route Handlers don't need this — request.text() always returns raw bytes.console.log(event.eventType, event.eventId) at the top of processEvent.ngrok http 3000) and update the destination URL to the tunnel.subscription.created simulation against your destination.client.notifications.logs.list(notificationSettingId, { per_page: 50 }) returns the same — note the path is nested under notifications, not a top-level resource, and notificationSettingId is a positional path param.).env.local and re-simulate. Confirm:
checkout-web) and confirm the resulting transaction.completed and subscription.created events arrive.src/app/api/webhook/route.ts and src/utils/paddle/process-webhook.ts.// utils/paddle/get-paddle-instance.ts
import {
Environment,
LogLevel,
Paddle,
type PaddleOptions,
} from "@paddle/paddle-node-sdk";
export function getPaddleInstance() {
const options: PaddleOptions = {
environment:
(process.env.NEXT_PUBLIC_PADDLE_ENV as Environment) ??
Environment.sandbox,
logLevel: LogLevel.error,
};
if (!process.env.PADDLE_API_KEY) {
throw new Error("PADDLE_API_KEY is not set");
}
return new Paddle(process.env.PADDLE_API_KEY, options);
}// app/api/webhook/route.ts
import { NextRequest } from "next/server";
import { getPaddleInstance } from "@/utils/paddle/get-paddle-instance";
import { processEvent } from "@/utils/paddle/process-webhook";
export async function POST(request: NextRequest) {
const signature = request.headers.get("paddle-signature") ?? "";
const rawBody = await request.text();
const secret = process.env.PADDLE_NOTIFICATION_WEBHOOK_SECRET ?? "";
// Pre-validation: a request with no signature header or empty body
// can't be verified or processed. 400 is fine here — Paddle will still
// retry, but that's okay; this is a "you sent us nothing" case.
if (!signature || !rawBody) {
return Response.json(
{ error: "Missing signature or body" },
{ status: 400 },
);
}
try {
const paddle = getPaddleInstance();
// Throws on signature mismatch, expired timestamp, or malformed event.
const eventData = await paddle.webhooks.unmarshal(
rawBody,
secret,
signature,
);
if (eventData) {
await processEvent(eventData);
}
// Acknowledge fast. Heavy work belongs in a queue (see Step 6).
return Response.json({ received: true });
} catch (e) {
console.error("Webhook error:", e);
// Any non-2xx tells Paddle to retry — 401 and 500 are equally fine here;
// only a 2xx would mark the event delivered and lose it. A thrown
// unmarshal could be a tampered request OR a rotated secret that hasn't
// been redeployed — they're indistinguishable, so retrying recovers the
// second case automatically and the first is harmless. We return 500.
return Response.json({ error: "Internal error" }, { status: 500 });
}
}// utils/paddle/process-webhook.ts
import {
type EventEntity,
EventName,
type SubscriptionCreatedEvent,
type SubscriptionUpdatedEvent,
type SubscriptionCanceledEvent,
type TransactionCompletedEvent,
type CustomerCreatedEvent,
type CustomerUpdatedEvent,
} from "@paddle/paddle-node-sdk";
/**
* Paddle delivers at-least-once. The same event.eventId arrives on every retry,
* so every handler below MUST be idempotent — UPSERT keyed on the Paddle
* resource id, or dedupe on event.eventId before non-DB side effects.
*/
export async function processEvent(event: EventEntity) {
// Idempotency: handlers may run multiple times for the same event.eventId.
switch (event.eventType) {
case EventName.SubscriptionCreated:
case EventName.SubscriptionUpdated:
case EventName.SubscriptionCanceled:
return handleSubscription(event);
case EventName.TransactionCompleted:
return handleTransactionCompleted(event);
case EventName.CustomerCreated:
case EventName.CustomerUpdated:
return handleCustomer(event);
default:
// Subscribed to events you don't handle yet? No-op. Better than throwing.
return;
}
}
async function handleSubscription(
event:
| SubscriptionCreatedEvent
| SubscriptionUpdatedEvent
| SubscriptionCanceledEvent,
) {
// TODO: idempotent UPSERT keyed on event.data.id. See subscription-sync.
// e.g. db.subscriptions.upsert({ where: { id: event.data.id }, update: {...}, create: {...} })
}
async function handleTransactionCompleted(event: TransactionCompletedEvent) {
// TODO: idempotent UPSERT keyed on event.data.id, OR dedupe on event.eventId
// before non-DB side effects (sending receipts, granting credits).
}
async function handleCustomer(
event: CustomerCreatedEvent | CustomerUpdatedEvent,
) {
// TODO: idempotent UPSERT keyed on event.data.id.
}async function handleSubscription(
event:
| SubscriptionCreatedEvent
| SubscriptionUpdatedEvent
| SubscriptionCanceledEvent,
) {
await db.subscriptions.upsert({
where: { id: event.data.id },
update: {
status: event.data.status,
currentBillingPeriod: event.data.currentBillingPeriod,
},
create: {
/* ... */
},
});
}import { db } from "@/lib/db";
export async function processEvent(event: EventEntity) {
const seen = await db.processedWebhooks.findUnique({
where: { eventId: event.eventId },
});
if (seen) return; // Already handled — return 200 from the route.
await db.$transaction(async (tx) => {
await routeEvent(event, tx);
await tx.processedWebhooks.create({ data: { eventId: event.eventId } });
});
}CREATE TABLE processed_webhooks (
event_id TEXT PRIMARY KEY,
processed_at TIMESTAMP NOT NULL DEFAULT NOW()
);ngrok http 3000
# Use the https URL as your notification destination URL: https://abc123.ngrok.app/api/webhook