Skip to content
HookDeploy

Paddle webhooks

Last verified against Paddle's documentation on September 27, 2026.

On this page ↓

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:

AreaKey eventsTypical use
Transactionstransaction.completed, transaction.paid, transaction.payment_failed, transaction.past_dueFulfill orders, grant access, handle failed payments
Subscriptionssubscription.created, subscription.activated, subscription.updated, subscription.canceled, subscription.past_due, subscription.paused, subscription.resumed, subscription.trialingKeep access and plan state in sync
Customerscustomer.created, customer.updatedSync customer records
Adjustmentsadjustment.created, adjustment.updatedHandle refunds and credits
Payoutspayout.created, payout.paidReconcile money arriving in your account
Catalogproduct.created, product.updated, price.created, price.updatedMirror your product catalog
Securityapi_key.expiring, api_key_exposure.createdRotate 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

BehaviorDetail
Signature headerPaddle-Signature, formatted ts=<timestamp>;h1=<signature>
Signing schemeHMAC-SHA256 over {ts}:{raw body}, keyed with the notification destination’s secret key
Timestamp tolerancePaddle’s SDKs reject signatures more than five seconds old by default
Secret keyOne per notification destination, starting pdl_ntfset_
Expected response200 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 retriesThe notification is marked failed. The replay a notification API can redeliver it
OrderingNot guaranteed. Check occurred_at before changing records
Source IPsSix published IPv4 addresses for live, and six for sandbox
User agentContains 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 expects 200, 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:

  1. Verify the HMAC on every request. A valid HMAC proves Paddle created the payload.
  2. If the timestamp is fresh, process it normally.
  3. 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.
  4. 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

  1. In HookDeploy, create an endpoint (for example, Paddle live) and copy its URL.
  2. On the endpoint’s Security tab, under Network, add Paddle’s IP addresses for your environment (Starter and above).
  3. 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.
  4. 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.
  5. 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.

Capture Paddle webhooks free

Start free