# 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](https://classic.paddle.com/webhooks/verifying-webhooks/).

Agent skill: `npx skills add hookdeck/webhook-skills --skill paddle-webhooks` ([details](https://hookdeck.com/webhooks/paddle/skill))

> Independent reference generated from hookdeck/webhook-registry (commit a24c8d9, 19 Nov 2026). [Paddle's official docs](https://developer.paddle.com/webhooks/about/how-webhooks-work/).

[Overview](https://hookdeck.com/webhooks/paddle) · [Webhook events (59)](https://hookdeck.com/webhooks/paddle/events) · [MCP events](https://hookdeck.com/webhooks/paddle/mcp-events) · [Verify signatures](https://hookdeck.com/webhooks/paddle/verify) · [Production guide](https://hookdeck.com/webhooks/paddle/guide-duplicates-ordering-retries-timeouts) · [Agent skill](https://hookdeck.com/webhooks/paddle/skill)

## Key facts

| Fact | Value | Source |
|---|---|---|
| Signature header | `Paddle-Signature` Format: ts=<unix seconds>;h1=<hex> | [Paddle docs](https://developer.paddle.com/webhooks/about/signature-verification) |
| Scheme | `HMAC-SHA256` | [Paddle docs](https://developer.paddle.com/webhooks/about/signature-verification) |
| Signed material | `{ts}:{raw body}` ts from the Paddle-Signature header, a literal colon, then the request body exactly as sent. | [Paddle docs](https://developer.paddle.com/webhooks/about/signature-verification) |
| How events are identified | `event_type field in the body` | [Paddle docs](https://developer.paddle.com/webhooks/about/how-webhooks-work) |
| Body format | `JSON` Content type: application/json. | [Paddle docs](https://developer.paddle.com/webhooks/about/respond-to-webhooks) |
| Replay window | `5 seconds` The default tolerance in Paddle's SDKs. If you verify manually the check is optional. | [Paddle docs](https://developer.paddle.com/webhooks/about/signature-verification) |
| Envelope | `event_id, event_type, occurred_at, notification_id, data` | [Paddle docs](https://developer.paddle.com/webhooks/about/how-webhooks-work/) |
| Agent skill | `npx skills add hookdeck/webhook-skills --skill paddle-webhooks` | [Agent skill →](https://hookdeck.com/webhooks/paddle/skill) |

[Verify Paddle webhooks](https://hookdeck.com/webhooks/paddle/verify)

## 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.

## 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-Signature` header. 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](/docs/cli): `hookdeck listen 3000 paddle --path /api/webhook`.
- Resend a `delivered` or `failed` notification with `POST /notifications/{notification_id}/replay`. Notifications older than 90 days aren't retained, so they can't be replayed.

## Delivery behaviour

- **Timeout:** 5 seconds. to return a `200`; any other response counts as a failure. [Guide](https://hookdeck.com/webhooks/paddle/guide-duplicates-ordering-retries-timeouts#timeouts)
- **Retries:** up to 60 attempts. over about 2 days on live accounts; 3 attempts in about 2 minutes on sandbox. [Guide](https://hookdeck.com/webhooks/paddle/guide-duplicates-ordering-retries-timeouts#retries)
- **After retries:** marked failed. no more automatic attempts; replay it with the API within 90 days. [Guide](https://hookdeck.com/webhooks/paddle/guide-duplicates-ordering-retries-timeouts#retries)
- **Ordering:** not guaranteed. compare `occurred_at` before changing state. [Guide](https://hookdeck.com/webhooks/paddle/guide-duplicates-ordering-retries-timeouts#ordering)

## Known failure modes

1. **Duplicate deliveries.** Paddle delivers at least once, so the same event can arrive twice. Deduplicate on `event_id`, because `notification_id` differs for each destination and each replay. [Handle duplicates](https://hookdeck.com/webhooks/paddle/guide-duplicates-ordering-retries-timeouts#duplicates)
2. **Out-of-order delivery.** Paddle can't guarantee delivery order. Store the latest `occurred_at` for each entity and don't let an older event overwrite newer state. [Handle ordering](https://hookdeck.com/webhooks/paddle/guide-duplicates-ordering-retries-timeouts#ordering)
3. **Handlers that take longer than five seconds.** If your handler doesn't return a `200` within five seconds, Paddle counts the delivery as failed and retries, even if the work finished. Respond first, then process the event from a queue. [Handle timeouts](https://hookdeck.com/webhooks/paddle/guide-duplicates-ordering-retries-timeouts#timeouts)
4. **Notifications that end up failed.** On live accounts Paddle stops after up to 60 attempts over about two days and marks the notification `failed`. Replay it with the API within 90 days, after which it's no longer retained. [Retries and replay](https://hookdeck.com/webhooks/paddle/guide-duplicates-ordering-retries-timeouts#retries)

From [Hookdeck's Paddle guide](https://hookdeck.com/webhooks/paddle/guide-duplicates-ordering-retries-timeouts).

## Paddle webhook best practices

- **[Verify every signature](https://hookdeck.com/webhooks/paddle/verify).** Without it, anyone who finds your URL can send fake events and trigger actions like granting access.
- **[Return a 200 before doing any work](https://hookdeck.com/webhooks/paddle/guide-duplicates-ordering-retries-timeouts#timeouts).** 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](https://hookdeck.com/webhooks/paddle/guide-duplicates-ordering-retries-timeouts#timeouts).** Queueing keeps the request path short and stops a spike in webhooks from overwhelming your server.
- **[Deduplicate on event_id](https://hookdeck.com/webhooks/paddle/guide-duplicates-ordering-retries-timeouts#duplicates).** Paddle delivers at least once. Store each `event_id` you process and skip any you've already seen.
- **[Check occurred_at before changing state](https://hookdeck.com/webhooks/paddle/guide-duplicates-ordering-retries-timeouts#ordering).** Paddle can't guarantee delivery order, so an older event shouldn't overwrite newer state.
- **[Subscribe only to events you process](https://hookdeck.com/webhooks/paddle/guide-duplicates-ordering-retries-timeouts#choosing-events).** A checkout alone produces several events across transactions, customers, addresses and subscriptions.

## Common Paddle webhook events

### Subscriptions

- [subscription.created](https://hookdeck.com/webhooks/paddle/events#subscription.created): New subscription is created
- [subscription.activated](https://hookdeck.com/webhooks/paddle/events#subscription.activated): Subscription turns active after any trial and a successful bill
- [subscription.updated](https://hookdeck.com/webhooks/paddle/events#subscription.updated): Subscription changes, including items, billing details and scheduled changes
- [subscription.past_due](https://hookdeck.com/webhooks/paddle/events#subscription.past_due): Subscription has an unpaid transaction
- [subscription.canceled](https://hookdeck.com/webhooks/paddle/events#subscription.canceled): Subscription moves to canceled

### Transactions

- [transaction.paid](https://hookdeck.com/webhooks/paddle/events#transaction.paid): Payment is captured, before Paddle finishes processing
- [transaction.completed](https://hookdeck.com/webhooks/paddle/events#transaction.completed): Paddle finishes processing a paid transaction
- [transaction.payment_failed](https://hookdeck.com/webhooks/paddle/events#transaction.payment_failed): Payment attempt fails

### Customers

- [customer.created](https://hookdeck.com/webhooks/paddle/events#customer.created): New customer is created
- [customer.updated](https://hookdeck.com/webhooks/paddle/events#customer.updated): Customer details change

## Events by resource

| Resource | Events | Payloads |
|---|---|---|
| [transaction](https://hookdeck.com/webhooks/paddle/events#resource-transaction) | 10 | 10 |
| [subscription](https://hookdeck.com/webhooks/paddle/events#resource-subscription) | 9 | 9 |
| [api_key](https://hookdeck.com/webhooks/paddle/events#resource-api-key) | 6 | 6 |
| [discount](https://hookdeck.com/webhooks/paddle/events#resource-discount) | 5 | 5 |
| [address](https://hookdeck.com/webhooks/paddle/events#resource-address) | 3 | 3 |
| [business](https://hookdeck.com/webhooks/paddle/events#resource-business) | 3 | 3 |
| [client_token](https://hookdeck.com/webhooks/paddle/events#resource-client-token) | 3 | 3 |
| [customer](https://hookdeck.com/webhooks/paddle/events#resource-customer) | 3 | 3 |
| [price](https://hookdeck.com/webhooks/paddle/events#resource-price) | 3 | 3 |
| [product](https://hookdeck.com/webhooks/paddle/events#resource-product) | 3 | 3 |

1 more resource. [All 59 events](https://hookdeck.com/webhooks/paddle/events)

## In this hub

- [Webhook events](https://hookdeck.com/webhooks/paddle/events): Every covered Paddle event, with payloads where the registry has them.
- [MCP events](https://hookdeck.com/webhooks/paddle/mcp-events): How an agent subscribes to Paddle events as MCP events.
- [Verify signatures](https://hookdeck.com/webhooks/paddle/verify): Signature facts, verification code and common failures.
- [Production guide](https://hookdeck.com/webhooks/paddle/guide-duplicates-ordering-retries-timeouts): Production problems: timeouts, duplicates, ordering and retries, and how to handle them.
- [Agent skill](https://hookdeck.com/webhooks/paddle/skill): Install the webhook skill in your coding agent. `npx skills add hookdeck/webhook-skills --skill paddle-webhooks`
---

Not affiliated with Paddle. Facts are compiled from public sources and linked inline. [View as JSON](https://hookdeck.com/webhooks/paddle.json) · [Report a correction](https://hookdeck.com/contact)
