Testing Paddle Webhooks

Use UseWebhook to capture, inspect, and forward Paddle webhooks to your local development server - no public endpoint required.

1. Grab your webhook URL

Head to UseWebhook and grab your unique webhook URL. This is the public HTTPS endpoint you'll give to Paddle.

2. Configure Paddle to send webhooks

Log into your Paddle dashboard and navigate to Developer Tools > Notifications. Click New destination and configure it:

• URL: Paste your UseWebhook URL
• Description: e.g. "Local development"
• Events: Select the events you want to receive (e.g. transaction.completed, subscription.activated, subscription.updated, subscription.canceled)

Save the destination. Paddle will now send webhook events to your UseWebhook URL.

3. Trigger a test event

You can trigger a webhook event from Paddle in a few ways:

Using Paddle's built-in simulator:

In your Paddle dashboard, go to Developer Tools > Notifications, select your destination, and click Send test notification. Choose an event type like transaction.completed to fire a test payload.

Using a real checkout:

If you're using Paddle Sandbox, complete a test checkout using Paddle's test card numbers. This will trigger real webhook events like transaction.completed and subscription.activated.

4. Inspect the webhook payload

After triggering an event, you'll see the request appear in your UseWebhook dashboard. You can inspect the full payload, including:

• Headers: Paddle sends a Paddle-Signature header used for webhook signature verification
• Body: The JSON payload containing the event type, data, and metadata

UseWebhook highlights any differences between consecutive requests, making it easy to spot changes between events - useful when comparing subscription.activated vs subscription.updated payloads.

5. Forward to localhost

Now let's forward incoming Paddle webhooks to your local development server. Install the UseWebhook CLI:

curl -fsSL https://usewebhook.com/install.sh | bash

Make sure your local server is running, then start forwarding:

usewebhook $YOUR_WEBHOOK_URL \
  --forward-to http://localhost:8000/webhooks/paddle/

Replace $YOUR_WEBHOOK_URL with your UseWebhook URL, and adjust the local URL to match your webhook endpoint.

Every Paddle event sent to your UseWebhook URL will now be forwarded to your local server, so you can test your webhook handler end-to-end.

6. Replay from webhook history

UseWebhook stores a history of all requests, so you can replay any Paddle event at any time. This is useful for:

• Reproducing bugs without triggering a new checkout
• Testing how your handler responds to different event types
• Iterating on your webhook logic without waiting for Paddle

Grab the request ID from your UseWebhook dashboard:

Then replay it:

usewebhook $YOUR_WEBHOOK_URL \
  --request-id $REQUEST_ID \
  --forward-to http://localhost:8000/webhooks/paddle/

You can also copy the full command from the dashboard using the "Copy as" dropdown.

Tips for testing Paddle webhooks

• Use Paddle Sandbox for development. It has separate API keys and won't affect real customers.
• Verify signatures locally. Paddle signs every webhook with an HMAC-SHA256 signature in the Paddle-Signature header. Make sure your local handler validates this using your webhook secret.
• Handle out-of-order events. Paddle doesn't guarantee delivery order. Your handler should use timestamps or sequence IDs to avoid processing stale events.
• Test failure scenarios. Try canceling a subscription or letting a payment fail to make sure your handler covers subscription.canceled and transaction.payment_failed events.

Conclusion

With UseWebhook, you can test Paddle webhooks without deploying to a public server. Capture events in your browser, forward them to localhost, and replay them as many times as you need.

Ready to try it out? Grab your webhook URL.