Paddle webhooks
Last verified against Paddle's documentation on September 27, 2026.
Paddle sends webhooks, which it calls notifications, when something happens in your Paddle Billing account: a transaction completes, a subscription renews, a payment fails. Paddle expects a 200 within five seconds, and its SDKs reject any signature older than five seconds. Most problems come from a parsed body breaking the signature, a slow handler, or a delivery that arrives after the window closes. This page covers what Paddle sends, how it delivers, how to fix the common errors, and where HookDeploy fits.
This page covers Paddle Billing. If you signed up before August 2023 and still use Paddle Classic, its webhooks work differently.
What Paddle sends webhooks for
Each notification destination subscribes to specific events. These are the ones most integrations use:
| Area | Key events | Typical use |
|---|---|---|
| Transactions | transaction.completed, transaction.paid, transaction.payment_failed, transaction.past_due | Fulfill orders, grant access, handle failed payments |
| Subscriptions | subscription.created, subscription.activated, subscription.updated, subscription.canceled, subscription.past_due, subscription.paused, subscription.resumed, subscription.trialing | Keep access and plan state in sync |
| Customers | customer.created, customer.updated | Sync customer records |
| Adjustments | adjustment.created, adjustment.updated | Handle refunds and credits |
| Payouts | payout.created, payout.paid | Reconcile money arriving in your account |
| Catalog | product.created, product.updated, price.created, price.updated | Mirror your product catalog |
| Security | api_key.expiring, api_key_exposure.created | Rotate API keys before they expire, and react to exposed keys |
Every notification is a JSON POST with an event_id, an event_type, an occurred_at timestamp, a notification_id, and the entity under data.
How Paddle delivers webhooks
| Behavior | Detail |
|---|---|
| Signature header | Paddle-Signature, formatted ts=<timestamp>;h1=<signature> |
| Signing scheme | HMAC-SHA256 over {ts}:{raw body}, keyed with the notification destination’s secret key |
| Timestamp tolerance | Paddle’s SDKs reject signatures more than five seconds old by default |
| Secret key | One per notification destination, starting pdl_ntfset_ |
| Expected response | 200 within five seconds |
| Retries (live) | 60 attempts over 3 days with exponential backoff: 20 in the first hour, 47 in the first day |
| Retries (sandbox) | 3 attempts within 15 minutes |
| After retries | The notification is marked failed. The replay a notification API can redeliver it |
| Ordering | Not guaranteed. Check occurred_at before changing records |
| Source IPs | Six published IPv4 addresses for live, and six for sandbox |
| User agent | Contains Paddle |
Common Paddle webhook errors and how to fix them
Signature verification fails
- The body was parsed first. Paddle signs the raw bytes, and its docs warn against adding whitespace or reformatting. Use a raw body parser on the webhook route, ahead of any JSON middleware.
- Wrong signed payload. It’s
{ts}:{body}, joined with a colon. Hashing only the body will never match. - Wrong secret. Each notification destination has its own secret key, and sandbox and live destinations have different ones.
- The timestamp is too old. See The five-second signature window.
Timeouts and cold starts
Paddle waits five seconds. Serverless handlers on cold start regularly take longer, and Paddle’s own docs suggest pre-warming functions for that reason. Respond with 200 before any processing, and queue the work.
Requests blocked by a firewall
Web application firewalls often treat Paddle’s requests as bot traffic. Exempt your webhook path from bot checks, and restrict the rule to Paddle’s IP addresses and a user agent containing Paddle.
Events out of order
Paddle doesn’t guarantee order, so a subscription.updated can arrive before the subscription.created it follows. Store occurred_at and ignore anything older than what you already have.
Duplicate events
Retries deliver the same event again. Record each event_id you process and skip repeats.
Notification marked failed
After Paddle’s retries run out (3 days in live), the notification is marked failed. Fix your endpoint, then redeliver it with the replay a notification API, or check delivery attempts with the notification logs API.
Why use HookDeploy with Paddle
Paddle’s own retries are generous: 60 attempts over three days. So HookDeploy’s value with Paddle isn’t mainly about retries. It’s everything around the delivery.
Inspect every notification
See the exact body and headers of every notification, including the Paddle-Signature value, alongside what your handler returned. When a signature check fails in your app but the request looks right in HookDeploy, you know the problem is between your server’s edge and your handler.
One notification, many systems
Send each Paddle event to your app, a data warehouse, and a finance channel in parallel, with one secret key to manage. A failing destination doesn’t hold up the others. Free includes 1 destination per endpoint, Starter includes 5, and Pro and above are unlimited.
Lock the endpoint to Paddle’s IPs
Paddle publishes its webhook IPs, and they’re IPv4, so HookDeploy’s IP allowlist works here. Add the live or sandbox list on the endpoint’s Security tab, under Network (Starter and above), and anything else is rejected before it’s captured.
Develop against real events
A tap sends a temporary copy of live or simulated Paddle events to 127.0.0.1 on your machine while production keeps receiving them. Taps arrive in real time, so signatures usually verify within Paddle’s five-second window.
Deliver to systems Paddle can’t reach
Paddle needs a public HTTPS URL. The HookDeploy Agent connects outward from your network over mTLS and delivers notifications to a local port, so billing events can reach private infrastructure with no public IP or open port.
Know the trade-offs
- HookDeploy’s retries replace Paddle’s. Once HookDeploy responds with
200, Paddle stops retrying. Starter retries 3 times over about 35 minutes, and Pro and Scale up to 5 times on a schedule you choose, which is much shorter than Paddle’s three days. Incidents and replay cover anything after that. - Retries and replays arrive after the signature window. Plan for that with the pattern below.
- Keep the response a
200. Paddle expects200, and HookDeploy’s default capture response is one. Don’t set a custom response with a different status on a Paddle endpoint. - Plan limits. On Free, requests beyond the monthly allowance or the daily limit get a
429, which Paddle treats as a failed delivery and retries. Paid plans keep accepting traffic past the included volume.
The five-second signature window
Paddle signs each delivery with a timestamp, and its SDKs reject signatures older than five seconds. HookDeploy forwards the first delivery right after capture, so it normally arrives inside that window. But every retry and every replay re-sends Paddle’s original signature, and arrives well after it.
Loosening the tolerance everywhere would weaken the replay protection it exists for. A safer pattern:
- Verify the HMAC on every request. A valid HMAC proves Paddle created the payload.
- If the timestamp is fresh, process it normally.
- If only the timestamp is stale, accept it only when the request carries an auth header you inject on the HookDeploy destination. Then fetch the notification from Paddle’s API using its
notification_id, with your API key, and process what Paddle returns. - Deduplicate on
event_id, however the event arrived.
Data fetched from Paddle’s API with your key is authentic by definition, so this handles retries and replays of any age.
Set up Paddle with HookDeploy
- In HookDeploy, create an endpoint (for example,
Paddle live) and copy its URL. - On the endpoint’s Security tab, under Network, add Paddle’s IP addresses for your environment (Starter and above).
- On the Forwarding tab, add a destination pointing to your handler, or to an agent for private delivery. Add a header
Authorization: Bearer YOUR_HANDLER_SECRET, and set the destination’s retries. - In Paddle, go to Developer tools, then Notifications, and create a notification destination of type URL. Paste your HookDeploy URL, choose your events, and copy the destination’s secret key.
- Send a test with Paddle’s webhook simulator, and confirm it appears in HookDeploy and reaches your handler.
Example handler (Node.js and Express)
import crypto from 'node:crypto';
import express from 'express';
const app = express();
const TOLERANCE_SECONDS = 5;
const hookdeployAuth = Buffer.from(`Bearer ${process.env.HANDLER_SECRET}`);
// Raw body parser on this route, registered before any global JSON middleware.
app.post('/webhooks/paddle', express.raw({ type: 'application/json' }), async (req, res) => {
const pairs = (req.get('paddle-signature') ?? '').split(';').map((p) => p.split('='));
const ts = pairs.find(([k]) => k === 'ts')?.[1] ?? '';
const signatures = pairs.filter(([k]) => k === 'h1').map(([, v]) => v);
const expected = crypto
.createHmac('sha256', process.env.PADDLE_WEBHOOK_SECRET)
.update(`${ts}:${req.body.toString('utf8')}`) // raw bytes, untouched
.digest('hex');
const valid = signatures.some(
(sig) => sig.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))
);
if (!valid) return res.status(401).send('Invalid signature');
const fresh = Math.abs(Date.now() / 1000 - Number(ts)) <= TOLERANCE_SECONDS;
if (!fresh && !isFromHookDeploy(req)) return res.status(401).send('Stale signature');
res.sendStatus(200); // Paddle expects a 200 within five seconds
const event = JSON.parse(req.body.toString('utf8'));
// Late deliveries: your worker fetches the notification from Paddle's API before acting.
await enqueue({ eventId: event.event_id, notificationId: event.notification_id, fresh, event });
});
function isFromHookDeploy(req) {
const received = Buffer.from(req.get('authorization') ?? '');
return received.length === hookdeployAuth.length &&
crypto.timingSafeEqual(received, hookdeployAuth);
}
FAQ
Why does my Paddle signature check fail on retries?
Paddle's SDKs reject any webhook whose signature timestamp is more than five seconds old. A retry or replay re-sends the original signature, so it arrives after that window and fails the default check, even though the signature is genuine.
Is this page about Paddle Billing or Paddle Classic?
Paddle Billing, which everyone who signed up after August 2023 uses. Paddle Classic webhooks work differently. They put the signature in the payload and verify it with PHP serialization, while Paddle Billing uses the Paddle-Signature header.
Does HookDeploy break Paddle signature verification?
Not on first delivery. HookDeploy forwards Paddle's original body and Paddle-Signature header unchanged, so your handler verifies it as if Paddle had called it directly. Retries and replays arrive after Paddle's five-second window, a transformation changes the body, and a privacy filter changes the stored copy used for retries and replays.
Can I allowlist Paddle's IP addresses on HookDeploy?
Yes. Paddle publishes six IPv4 webhook addresses for live accounts and six for sandbox. Add the list for your environment to the endpoint's IP allowlist on the Security tab, under Network, available on Starter and above.
How do I test Paddle webhooks locally?
Point a notification destination at HookDeploy and send events with Paddle's webhook simulator, which sends exact replicas including the Paddle-Signature header. Then start a tap from the Desktop Agent or CLI to copy them to a local port, or replay a captured event to your local handler.
Does Paddle retry failed webhooks?
Yes. Live accounts get 60 retries over 3 days, and sandbox accounts get 3 retries within 15 minutes. After that, the notification is marked failed, and you can redeliver it with Paddle's replay a notification API.