Contents

Chapter 2. Installation, Updates, and Support
PrevNext

Setting Up Webhooks

Paddle tells your site about each payment, renewal, refund and change by sending a webhook to a web address on your site. Without webhooks, customers pay but never get access.

Procedure 2.4. Add your site as a notification destination

  1. In Paddle, go to Events → Notifications and click New destination.

  2. Give it a description, choose Webhook as the type, and enter this URL, with your own site's address:

    https://www.example.com/index.php?option=com_paddlesubs&task=webhooks.process

    Until you enter an API key, the Get Started page shows this URL with your site's address already filled in, ready to copy.

  3. Choose the events to send. PaddleSubs acts on these:

    transaction.createdsubscription.canceled
    transaction.updatedcustomer.created
    transaction.completedcustomer.updated
    transaction.canceledadjustment.created
    subscription.createdadjustment.updated
    subscription.updated 

    Choosing every event does no harm; PaddleSubs records the others and does nothing with them. Appendix A, How PaddleSubs Handles Each Paddle Event says what each event does.

  4. Save the destination.

  5. Get the destination's secret key, which your site uses to check that each webhook really comes from Paddle: click … beside the destination, then Edit destination, and copy the secret key shown there.

Procedure 2.5. Enter the secret key in PaddleSubs

  1. In PaddleSubs' Options, open the Webhooks tab.

  2. Paste the key into Sandbox webhook secret key (or, while Environment is Production, Webhook secret key).

  3. Leave Sandbox webhook addresses (or Webhook addresses) as it is: it already holds the IP addresses Paddle publishes. If your site is behind a proxy or a service such as Cloudflare, enter the proxy's addresses in Trusted proxies; otherwise leave it empty.

  4. Click Save & Close.

Warning

Without the secret key, webhooks don't work: your site refuses every one, so customers who pay get no access, and renewals, refunds and changes are never recorded. Until you enter it, every PaddleSubs page, the dashboard included, says so in red (Webhooks are not working.), and the Get Started page stays open instead of moving on to the dashboard.

PaddleSubs refuses any webhook that doesn't come from one of those addresses, or isn't signed with the destination's secret key, and refuses anything but a POST request, answering with an error status that Paddle's log shows. Paddle retries a webhook your site refused or didn't answer, for a few days. Paddle's notification log shows whether your site accepted each one; see Q:  if it didn't.

When a webhook is accepted, it is saved in a queue and processed by the webhook processor task, so it doesn't matter if several arrive at once or out of order.

On this page