Webhook events and what they do
The exact list to subscribe to in Paddle, and the action each one triggers.
Subscribe your Paddle notification destination to these events. Anything else is accepted, logged, and ignored.
| Paddle event | What the panel does |
|---|---|
transaction.completed |
Finds or creates the user, records the order and transaction, and creates a subscription with a fresh license key. This is the event that fulfils a sale. |
subscription.created |
Confirms the subscription record exists and links the Paddle subscription ID. |
subscription.updated |
Updates status, current period end, and the plan if it changed. Extends the update window on a renewal. |
subscription.canceled |
Marks the subscription canceled and stamps the cancellation time. |
subscription.paused |
Moves the subscription out of active status. |
subscription.resumed |
Returns it to active. |
subscription.past_due |
Reflects the past-due state on the subscription. |
transaction.payment_failed |
Emails the customer that their payment failed, so they can update their card before the subscription lapses. |
The user is created for you#
A buyer never fills in a registration form. On transaction.completed the panel resolves the account in this order:
- An existing user with that Paddle customer ID.
- An existing user with that email address — which is linked to the Paddle customer ID, so a returning buyer keeps one account.
- Otherwise, a new user with no password, email already marked verified, and the customer role.
A newly created user is emailed a welcome message containing a signed set-password link. Until they use it, they are held on that screen and cannot reach the rest of the customer panel.
Idempotency#
Every webhook is recorded against its Paddle event ID before it is processed. If the same event arrives twice — which Paddle will do after a timeout — the second copy is recognised as already processed and returns without doing the work again. A retry can never double-issue a license or double-charge a referral commission.
Failures#
If processing throws, the log row is marked failed with the error message and the attempt count, and the error propagates so Paddle knows to retry. The panel also retries failed events on its own schedule; see Webhook logs and retries.