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.

59 events covered

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

Signature header
Paddle-Signature

Format: ts=<unix seconds>;h1=<hex>

Scheme
HMAC-SHA256
Signed material
{ts}:{raw body}

ts from the Paddle-Signature header, a literal colon, then the request body exactly as sent.

How events are identified
event_type field in the body
Body format
JSON

Content type: application/json.

Replay window
5 seconds

The default tolerance in Paddle's SDKs. If you verify manually the check is optional.

Envelope
event_id, event_type, occurred_at, notification_id, data
Agent skill
npx skills add hookdeck/webhook-skills --skill paddle-webhooks

Verify Paddle webhooks →

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: 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

  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 →
  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 →
  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 →
  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 →

Paddle webhook best practices

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

transaction.billed · .canceled · .completed · .created +6

10 10
subscription

subscription.activated · .canceled · .created · .imported +5

9 9
api_key

api_key.created · .expired · .expiring · .revoked +2

6 6
discount

discount.created · .imported · .updated · _group.created +1

5 5
address

address.created · .imported · .updated

3 3
business

business.created · .imported · .updated

3 3
client_token

client_token.created · .revoked · .updated

3 3
customer

customer.created · .imported · .updated

3 3
price

price.created · .imported · .updated

3 3
product

product.created · .imported · .updated

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.

Not affiliated with Paddle. Facts are compiled from public sources and linked inline.