paddle-webhooks

Receive Paddle webhooks securely in Next.js

When to use this skill

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.

The delivery contract

Every design choice in this skill follows from these facts about how Paddle delivers webhooks. Read this section first; everything else is mechanics.

• Only 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.
• Retry schedule. Sandbox: 3 attempts over ~15 minutes. Live: 60 attempts over ~3 days, exponential backoff (~60s × attempt^1.1). Connection timeouts count toward the same budget as non-2xx responses.
• Same 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.
• No redirect following. A 301 or 302 is treated as a failed delivery, not followed.
• After the retry budget is exhausted, the event is gone. You can replay manually from the dashboard's notification log, or via the Paddle MCP server with 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.