Working with Paddle webhooks
Introduction
With Paddle, it's easy to create and sell one-time digital products and subscription plans. We take care of product fulfillment (license keys, download links, etc.) and subscription management (recurring billing, upgrades, downgrades, failed payments, etc.).
However, the other side of the coin is your own platform - how does your database or CRM know when updates happen or payments succeed/fail? The answer is webhooks.
To be notified whenever items are purchased or something happens with an existing customer subscription, configure Paddle webhooks. Webhook payloads contain information for your backend system to consume and determine what action is needed - for example, grant access to your service when a new subscription plan is created or revoke access when an existing subscription plan is canceled.
What Paddle webhooks are available?
Webhooks are available for:
| Category | Summary |
|---|---|
| Subscription events | Events are available for the entire lifecycle of a subscription - from creation through to cancellation and everything in between. |
| One-Off purchase events | Receive notifications about new orders, payments, and refunds for one-time digital products. |
| Risk & dispute events | Monitor potentially fraudulent transactions and chargeback activity. |
| Payout events | Get notified when you receive a payout from your Paddle account. |
| Audience events | Get notified when a customer opts in to marketing communications or when a customer changes their marketing comms preference. |
| Manual invoicing events | Get notified when manual invoices are sent and when payments are received. |
Please see our Webhook reference for detailed information about all available webhooks.
How do I configure Paddle webhooks?
To receive webhook events, you need to tell Paddle:
- Which events to send
- Where to send them
To do this, use the Paddle dashboard:
- From the left-hand navigation menu, select Developer Tools and then Events:
... the Paddle Events page is displayed. The top half of this page is concerned with general setup and testing for webhooks:...the lower section lists all available Paddle events:
- In the top section, move to the Receiving events field and enter the URL that you'd like to use:
- In the lower Subscribing to events section, click the checkbox associated with any events that you want to receive from Paddle:
- Click the Save Changes button at the end of the page.
How can I test Paddle webhooks?
The Webhook Simulator is available from the top section of the Developer Tools > Events page:
Here, you can choose any Paddle event, enter a test URL (for receiving the alert), adjust pre-populated sample data (if required), and click the Call Webhook button to simulate the alert.
When the webhook call is made, the request payload is generated and displayed - for example:
If you haven't confirmed your webhook URL yet, use a URL provided by a webhook testing service such as webhook.site, ngrok, or Expose.
If you simply want to see the payload for a webhook, just enter any https:// address in the URL field.
Responding to Paddle webhooks
Having fired an alert to your webhook, Paddle expects an HTTP 200 response within 10 seconds, indicating that the message was received successfully.
If there is no response within 10 seconds - or if anything other than an HTTP 200 status code is received - Paddle retries the call to your webhook URL every 15 minutes for a maximum of 3 days.
Webhook whitelisting & security
To ensure that your integration receives events from Paddle, a set of Paddle IP addresses should be whitelisted. See our Webhook security guide for details.
For security, Paddle sends a p_signature field with each webhook, which can be used to verify that the webhook was sent by Paddle. See our Verifying webhooks guide for details.
Further information
Webhooks are a vital aspect of any Paddle integration. For further information, please see our Webhook reference.
For detailed information about managing the subscription lifecycle using webhooks, see our Access management using webhooks guide.