Paddle webhooks
Paddle Billing webhooks are HTTP POST requests that Paddle sends to your endpoint when something happens in your account, such as a subscription being created or a transaction completing.
These pages cover Paddle Billing, which everyone who signed up after 8 August 2023 has. Paddle Classic is a separate legacy product that verifies webhooks differently, with a `p_signature` body field and a public key.
How Paddle webhooks work
Webhooks push events to your server as they happen, so you don't have to poll Paddle's /events API for changes. When an event occurs, Paddle sends an HTTPS POST with a JSON body to each notification destination subscribed to it, and retries if it doesn't get a 200 within five seconds.
Every body has the same top level. event_type says what happened, such as transaction.completed, occurred_at says when, and data is a snapshot of the entity at that moment. event_id identifies the event, while notification_id identifies one notification to one destination, so two destinations share an event_id. Each destination also sets the API version its entities conform to.
Key facts
{ts}:{raw body} ts from the Paddle-Signature header, a literal colon, then the request body exactly as sent.
5 seconds The default tolerance in Paddle's SDKs. If you verify manually the check is optional.
Setting up Paddle webhooks
- Create a notification destination under Paddle > Events > Notifications, or with
POST /notification-settings, and choose its events. Only 10 destinations can be active at once. - Send test events with the webhook simulator, which delivers single events or scenarios such as a subscription renewal to your URL with a real
Paddle-Signatureheader. A destination's usage type sets whether it receives real events, simulated events or both. - Destinations need public URLs. To test locally, Paddle's docs suggest a tunnel such as the Hookdeck CLI:
hookdeck listen 3000 paddle --path /api/webhook. - Resend a
deliveredorfailednotification withPOST /notifications/{notification_id}/replay. Notifications older than 90 days aren't retained, so they can't be replayed.
Delivery behaviour
5 seconds to return a 200; any other response counts as a failure Retries up to 60 attempts over about 2 days on live accounts; 3 attempts in about 2 minutes on sandbox After retries marked failed no more automatic attempts; replay it with the API within 90 days Ordering not guaranteed compare occurred_at before changing state Known failure modes
From Hookdeck's Paddle guide →-
Duplicate deliveries
Paddle delivers at least once, so the same event can arrive twice. Deduplicate on
Handle duplicates →event_id, becausenotification_iddiffers for each destination and each replay. -
Out-of-order delivery
Paddle can't guarantee delivery order. Store the latest
Handle ordering →occurred_atfor each entity and don't let an older event overwrite newer state. -
Handlers that take longer than five seconds
If your handler doesn't return a
Handle timeouts →200within five seconds, Paddle counts the delivery as failed and retries, even if the work finished. Respond first, then process the event from a queue. -
Notifications that end up failed
On live accounts Paddle stops after up to 60 attempts over about two days and marks the notification
Retries and replay →failed. Replay it with the API within 90 days, after which it's no longer retained.
Paddle webhook best practices
- Verify every signature. Without it, anyone who finds your URL can send fake events and trigger actions like granting access.
- Return a 200 before doing any work. Paddle allows five seconds, and it retries on any other status code, so a slow handler gets the same event again.
- Process events from a queue. Queueing keeps the request path short and stops a spike in webhooks from overwhelming your server.
- Deduplicate on event_id.
Paddle delivers at least once. Store each
event_idyou process and skip any you've already seen. - Check occurred_at before changing state. Paddle can't guarantee delivery order, so an older event shouldn't overwrite newer state.
- Subscribe only to events you process. A checkout alone produces several events across transactions, customers, addresses and subscriptions.
Common Paddle webhook events
Subscriptions
subscription.created | New subscription is created |
subscription.activated | Subscription turns active after any trial and a successful bill |
subscription.updated | Subscription changes, including items, billing details and scheduled changes |
subscription.past_due | Subscription has an unpaid transaction |
subscription.canceled | Subscription moves to canceled |
Transactions
transaction.paid | Payment is captured, before Paddle finishes processing |
transaction.completed | Paddle finishes processing a paid transaction |
transaction.payment_failed | Payment attempt fails |
Customers
customer.created | New customer is created |
customer.updated | Customer details change |
Events by resource
| Resource | Events | Payloads |
|---|---|---|
transaction | 10 | 10 |
subscription | 9 | 9 |
api_key | 6 | 6 |
discount | 5 | 5 |
address | 3 | 3 |
business | 3 | 3 |
client_token | 3 | 3 |
customer | 3 | 3 |
price | 3 | 3 |
product | 3 | 3 |
1 more resource, including Other Paddle events. All 59 events →
In this hub
| Webhook events → | Every covered Paddle event, with payloads where the registry has them. |
| MCP events → | How an agent subscribes to Paddle events as MCP events. |
| Verify signatures → | Signature facts, verification code and common failures. |
| Production guide → | Production problems: timeouts, duplicates, ordering and retries, and how to handle them. |
| Agent skill → | Install the webhook skill in your coding agent. npx skills add hookdeck/webhook-skills --skill paddle-webhooks |
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.