Handle webhook delivery

Once you've created a notification destination, you should properly handle webhook delivery to make sure your integration performs well.

How it works

Webhooks let you subscribe to events in Paddle. When a subscribed event occurs, Paddle sends a notification to a webhook endpoint that you specify.

You can use notifications to keep your app in sync with Paddle, or to integrate with third-party systems. For example, when a subscription cancels, Paddle can send you a subscription.canceled webhook. When you receive this webhook, you can provision your app to make sure the canceled customer can no longer access your app.

To make sure your app or integration performs well, you should properly handle webhook delivery by making sure your webhook server is configured correctly, responding to notifications promptly, and handling retries.

Before you begin

Create a notification destination

Create a notification destination where the type is url (webhook), if you haven't already.

Allow Paddle IP addresses

You should make sure that webhooks originate from a Paddle webhook IP address. We recommend adding Paddle webhook IP addresses to your allowlist, and rejecting webhooks that come from other sources.

Allow different IP addresses for sandbox and live accounts:

1
2
3
4
5
6
134.194.127.46
254.234.237.108
33.208.120.145
444.226.236.210
544.241.183.62
6100.20.172.113

1
2
3
4
5
6
134.232.58.13
234.195.105.136
334.237.3.244
435.155.119.135
552.11.166.252
634.212.5.7

If you're using a Web Application Firewall (WAF) to protect your web server from bot traffic, requests from Paddle may be blocked incorrectly. We recommend configuring your firewall to bypass bot checks on webhook endpoint paths. Additionally, use Paddle IP addresses and match Paddle as the user agent string to further restrict your rule.

Configure your webhook handler

To receive webhooks, make sure your webhook event server:

• Uses HTTPS
• Can accept POST requests with a JSON payload
• Returns 200 within five seconds of receiving a request

We recommend configuring your handler to process webhooks asynchronously by queueing received events and processing them in order. This helps prevent a large spike in webhooks from overwhelming your server.

Respond to events

The server that you set to receive events from Paddle should respond with an HTTP 200 status code within five seconds. This lets Paddle know that you successfully received the message.

You should respond before doing any internal processing. For example, if you use a webhook to update a record in a third-party system, respond with a 200 before running any logic to communicate with the third-party solution.

We can't guarantee the order of delivery for webhooks. They may be delivered in a different order to the order they're generated. Store and check the occurred_at date against a webhook before making changes.

Handle retries

If your server sends another kind of status code or doesn't respond within five seconds, Paddle automatically retries using an exponential backoff schedule:

• For sandbox accounts, we retry 10 times for just under 15 minutes.
• For live accounts, we retry 60 times for just under 3 days. The first 20 attempts happen in the first hour, with 47 in the first day and 60 in total.

Use an exponential backoff calculator to visualize retries from the date now. Use these values:

You can check the status of a webhook and see delivery attempts using the Paddle dashboard, or by using the list logs for a notification operation in the Paddle API.

When all attempts to deliver a webhook are exhausted, its status is set to failed. You can attempt to redeliver a notification using the replay a notification operation in the Paddle API.

Verify webhook signatures

Use the Paddle-Signature header included with each webhook to verify that received events are genuinely sent by Paddle.

Related pages