Next.js Paddle webhook handler
A Paddle webhook route should verify the exact raw body before it grants access, sends downloads, updates subscriptions, or records refunds.
Route shape
Use a dedicated App Router route for Paddle. Read await request.text(), validate Paddle-Signature, parse JSON after verification, and map only trusted event fields into your billing model.
export async function POST(request: Request) {
const rawBody = await request.text();
const signature = request.headers.get("Paddle-Signature");
if (!signature || !verifyPaddleSignature(rawBody, signature)) {
return new Response("Invalid signature", { status: 400 });
}
const event = JSON.parse(rawBody);
await handlePaddleEventOnce(event);
return new Response("ok", { status: 200 });
}Event decisions
Keep the handler boring: verify, identify, dedupe, decide, then run one side effect. Avoid mixing checkout redirects, dashboard UI, and fulfillment into the webhook route.
Map the transaction to a user, confirm paid state, currency, total, product or price, then grant access once.
Activate, renew, pause, resume, downgrade, or cancel access with explicit period-end behavior.
Record support context, revoke or annotate access once, and keep refund rollback evidence.
Return 2xx after logging if safe, quarantine unrecognized payloads, and never grant access by default.
CI tests before checkout traffic
- Valid signed fixture returns 2xx.
- Mutated raw body returns 400 before side effects.
- Duplicate replay of the same event runs fulfillment once.
- Unpaid, pending, refunded, or unknown payloads do not grant access.
FAQ
What should a Next.js Paddle webhook handler do first?
Read await request.text(), verify the Paddle-Signature header against the exact raw body, and only then parse JSON or run billing side effects.
Which Paddle events should the handler test?
Start with transaction.completed, subscription lifecycle events, cancellation or pause events, and adjustment or refund events, then replay duplicates to prove idempotency.
Use the free sample before wiring production checkout
The free sample shows the fixture, handler, signature test, contract test, replay test, and CI shape. The Pro Kit preview shows the full CN¥69 paid package structure without exposing the private archive.