Paddle webhooks in production: duplicates, ordering, retries and timeouts
This guide covers the problems Paddle webhooks cause in production and how to handle each one. What Paddle sends and how it's signed is on the Paddle webhooks overview, every event type is on Paddle webhook events, and signature verification code is on Verify Paddle webhooks.
Everything here applies to Paddle Billing. Paddle Classic is a separate legacy product with its own webhooks.
At a glance
| Problem | What to do | With Event Gateway |
|---|---|---|
| Timeouts | Return a 200 within five seconds; process in a background job | Accepts the delivery at once, then queues it for your service |
| Duplicates | Record processed event_id values; make handlers idempotent | Drops repeats before they reach your handler |
| Ordering | Compare occurred_at; fetch current state when in doubt | Logs every event and attempt, so you can see arrival order when debugging |
| Retries | Watch for failed notifications; replay them within 90 days | Accepts deliveries while your service is down and replays them |
| Choosing events | Subscribe only to the events you process | Filters and routes events by type |
| Testing | Use the webhook simulator; forward events to localhost | Forwards to localhost and replays past events |
| Other limits | Plan for 10 active destinations, firewalls and fields left out of payloads | Fans one destination out to many services at a rate you set |
Paddle webhook timeouts and slow handlers
Return a 200 within five seconds, before doing any other work, then process the event in a background job.
Why it happens: Paddle treats any other status code, or no response within five seconds, as a failed delivery and retries it. Handlers that write to a database, provision access or call another API before responding can run past the limit, especially during a traffic spike. The work may have finished, but Paddle sends the event again. On serverless platforms, a cold start uses part of the five seconds before your code runs.
Fix it in your handler:
- Verify the signature and return
200straight away. - Push the event onto a queue (SQS, RabbitMQ or Redis) and process it in a worker. See why to process webhooks asynchronously.
- Keep the request path free of calls to other services.
- On Vercel Functions, AWS Lambda or Google Cloud Functions, pre-warm the function, as Paddle's docs suggest, to prevent intermittent timeouts from cold starts.
With Event Gateway: Hookdeck accepts each Paddle delivery immediately, then queues events and delivers them to your service at a rate it can handle, with its own retries. You set the delivery timeout per destination, with a default of 60 seconds. See how to solve Paddle webhook timeout errors.
Duplicate Paddle webhooks
Paddle guarantees at-least-once delivery, so the same event can arrive more than once. Record each event_id you process and skip repeats.
Why it happens: If your endpoint processes an event but doesn't return a 200 in time, Paddle retries it. Replaying a notification also creates a new notification for the same event. If two destinations point at the same handler, one event arrives once per destination, each time with the same event_id and a different notification_id.
Fix it in your handler:
- Deduplicate on
event_id.notification_iddiffers for each destination and each replay, so it misses those repeats. - Use a database table with a unique constraint on the id, and record it in the same transaction as the side effect.
- Make every handler idempotent: the same result however many times it runs.
- Don't treat a second
transaction.payment_for a transaction as a duplicate unless itsfailed event_idmatches. On live accounts you can get a new notification for each later payment retry that fails.
CREATE TABLE webhook_events (
event_id VARCHAR(50) PRIMARY KEY,
event_type VARCHAR(50),
processed_at TIMESTAMP DEFAULT NOW()
);
With Event Gateway: Hookdeck deduplicates events before they reach your endpoint, so repeats are filtered at the infrastructure level rather than in each handler.
Out-of-order Paddle webhooks
Paddle can't guarantee delivery order. Compare occurred_at before changing state, and don't rely on arrival order.
Why it happens: Paddle says webhooks may be delivered in a different order to the one they were generated in, and if one delivery fails and is retried, later events can overtake it. Related events also overlap: subscription.updated can follow subscription.activated as Paddle finishes processing. For more on the general problem, see Webhook Ordering: Why It's Hard and How to Handle It.
Fix it in your handler:
- Store the latest
occurred_atfor each entity, and ignore any event older than it. - Upsert rather than insert, so a
subscription.updatedthat arrives beforesubscription.createdstill works. - When an event is ambiguous or the operation is critical, treat the webhook as a signal and fetch the current state from the Paddle API.
async function handleEvent(payload) {
const entity = await db.findByPaddleId(payload.data.id);
if (entity && new Date(payload.occurred_at) <= new Date(entity.lastOccurredAt)) {
return; // Ignore stale events
}
await db.upsert({
paddleId: payload.data.id,
lastOccurredAt: payload.occurred_at,
...payload.data,
});
}
With Event Gateway: Hookdeck logs every event and delivery attempt, so when state looks wrong you can see the order events actually arrived in and replay them.
Paddle webhook retries and replay
On live accounts Paddle makes up to 60 attempts over about two days, then marks the notification failed. Sandbox makes 3 attempts in about two minutes. Replay failed notifications with the API.
Why it happens: Paddle retries with exponential backoff. On live accounts the wait before the next attempt is 60 * n^1.1 seconds, where n is the attempts made so far, which gives around 10 attempts in the first hour and around 45 in the first day. After the last attempt the status becomes failed and Paddle stops trying on its own. The API doesn't return events or notifications older than 90 days. Paddle's docs don't describe a failing destination being deactivated.
Fix it in your handler:
- Watch delivery status in the dashboard under Events > Notifications, or with the list notification logs operation.
- After an outage, list notifications with a
statusoffailedand resend each one withPOST /notifications/{notification_. A replay of a replay isn't allowed.id}/replay - Reconcile against the
/eventsendpoint to catch anything else you missed, and do it within the 90 days. - Don't judge outage handling from sandbox behaviour. Its retries end in about two minutes, where a live account keeps trying for about two days.
With Event Gateway: Hookdeck captures every Paddle delivery while your services are down, so Paddle's attempts succeed. Failed events can be retried automatically, manually or in bulk once you recover.
Choosing which Paddle events to listen to
Subscribe each notification destination only to the events your integration processes.
Why it matters: Every extra event type is a request your server has to accept, verify and discard, and a single checkout can send transaction.created, customer.created, address.created, business.created, transaction.paid, subscription.created and transaction.completed. The full list, with sample payloads, is on Paddle webhook events.
Fix it in your handler:
- For a new subscription, use
transaction.paidas the earliest sign that payment was captured,subscription.createdto record the subscription, andtransaction.completedto confirm Paddle has finished processing. A paid transaction may not yet have asubscription_idor an invoice number. - Handle
subscription.past_due,subscription.pausedandsubscription.canceledfor access changes. A cancellation scheduled for the next billing period first appears assubscription.updated, andsubscription.canceledoccurs on that date. - Sandbox and live are separate accounts that don't share notification destinations, so set up each one with its own URL.
With Event Gateway: Hookdeck filters and routes events by type or any other property, so one Paddle destination can feed several services.
Testing and debugging Paddle webhooks locally
Send test events with Paddle's webhook simulator, and use a tunnel to receive them on your machine.
Why it happens: Notification destinations need public URLs, and development machines sit behind NAT and firewalls. Producing a full flow by hand, such as a subscription renewal, takes real steps in Paddle.
Fix it in your handler:
- Use the webhook simulator to send single events or predefined scenarios for a subscription being created, renewed, paused, resumed or canceled. It works in sandbox and production without affecting real data.
- Test signature verification with it, because it sends the same request as a real webhook, including the
Paddle-Signatureheader. - Set a destination's usage type so that simulated events reach only the destinations you want.
- Remember what the simulator can't show: it sends one
transaction.payment_, where a live account can send one for each failed payment retry.failed
With Event Gateway: The Hookdeck CLI receives webhooks on your machine without a public server, and you can replay past events with one click. See how to test and replay Paddle webhooks locally.
Other Paddle webhook limits
Plan for Paddle's destination limit, firewalls, fields left out of payloads and the split between Billing and Classic before they reach production.
10 active destinations. You can create as many notification destinations as you want, but only 10 can be active at once. Consolidate them and route events internally if you run out.
IP allowlists and firewalls. Paddle recommends allowing only its webhook IP addresses, and publishes separate lists for sandbox and live. A Web Application Firewall can block Paddle's requests as bot traffic, so bypass bot checks on your webhook path and match on those addresses and the Paddle user agent.
Fields left out of payloads. Subscription events leave out management_urls, because those links are temporary, and discount events leave out times_used, because it changes often. Get them from the API when you need them.
Paddle Classic. Paddle Classic and Paddle Billing are separate products with different events and signatures, so moving to Billing means a new handler rather than a configuration change. Run both handlers during a migration, and listen for .imported events such as subscription.imported and customer.imported to update your records.
With Event Gateway: Hookdeck sends one Paddle destination's events to as many services as you need, absorbs spikes in its queue, and delivers at a rate you configure.
Give your Paddle handler more than five seconds.
Hookdeck Event Gateway accepts every Paddle delivery, verifies its signature, queues events and retries to your service on your schedule.