Paddle webhook test plan for Next.js
Before a Next.js app exposes Paddle checkout traffic, the webhook route needs proof that the exact raw body is signed, paid events are mapped to the right account, and duplicate deliveries do not repeat fulfillment.
Start with the Paddle-Signature gate
In a Next.js App Router route, read await request.text() before parsing JSON. Signature verification should use the exact payload string sent by Paddle and the endpoint signing secret for that environment.
- Valid signed payload returns 2xx.
- Mutated body returns 400 before any access grant.
- Wrong
Paddle-Signatureheader returns 400 before database writes, email delivery, or license generation.
Lock the Paddle contract fields
Keep fake, committed fixtures for checkout completion, the subscription lifecycle, subscription updates, cancellation, and adjustment or refund events. Tests should assert the fields your handler trusts before changing access.
Transaction ID, customer ID, address or business ID when used, status, currency, totals, product or price ID, and internal account mapping.
Subscription ID, customer ID, current billing period, scheduled change state, paid status, and initial entitlement decision.
Cancellation timing, period end, pause or resume state, downgrade behavior, and whether access remains active until the paid period ends.
Adjustment ID, related transaction, refund amount, rollback action, support note, and replay-safe revocation state.
Prove idempotency and duplicate replay
Paddle can retry webhook delivery. Store a provider-scoped idempotency key before fulfillment, then replay the same signed fixture three times. Duplicates can acknowledge success, but side effects should run once.
Keep checkout smoke separate
Fixture tests prove handler behavior. A controlled checkout smoke test proves deployed Paddle configuration, webhook delivery, environment variables, success redirects, and fulfillment. Keep both pieces in the release notes before a public buy link goes live.
FAQ
What should a Paddle webhook test plan include for Next.js?
Raw-body Paddle-Signature verification, signed transaction.completed and subscription fixtures, invalid signature rejection, idempotency storage, duplicate replay, entitlement decisions, checkout smoke evidence, and CI gates.
Can Paddle webhook tests run before a production Paddle checkout?
Yes. Route tests can use committed fake fixtures and fake signing secrets. A separate checkout smoke test is still required before production traffic.
Use the free sample before wiring production checkout
The free sample shows the shape of fixtures, handlers, signature tests, contract checks, duplicate replay tests, and CI workflow. The Pro Kit preview shows the full CN¥69 paid package structure without exposing the private archive.