Paddle Integration

Set up HookWatch to receive Paddle webhooks for billing events like subscription changes, completed transactions, and payment method updates.

Prerequisites

A HookWatch account
A Paddle account with Paddle Billing enabled
A server endpoint to process webhook payloads

Step 1: Create a HookWatch endpoint

Go to your Endpoints page
Click "Create Endpoint"
Enter a name like "Paddle Webhooks"
Enter your destination URL (where you want webhooks forwarded)
Copy the generated webhook URL

Your HookWatch URL will look like:

https://hook.hookwatch.dev/wh/abc123xyz

Step 2: Configure Paddle notification destination

Go to the Paddle Dashboard
Navigate to Developer Tools > Notifications
Click "New destination"
Enter a description like "HookWatch"
Paste your HookWatch URL in the "URL" field
Select the event types you want to subscribe to
Click "Save destination"

To get the webhook secret, go to Developer Tools > Notifications and copy the secret key shown for your notification destination.

Common event types:

subscription.created

subscription.updated

subscription.canceled

subscription.past_due

transaction.completed

transaction.payment_failed

customer.created

customer.updated

Step 3: Verify webhooks on your server

Paddle signs webhook payloads using HMAC-SHA256 with a specific signature format. HookWatch forwards the Paddle-Signature header which contains a timestamp and hash in the format ts=timestamp;h1=hash.

Node.js / Express

Important

Paddle Billing (v2) uses a different signature format than Paddle Classic. Make sure you're using the correct verification method for your Paddle version.

Paddle webhook headers

HookWatch forwards all Paddle headers. Here are the important ones:

Header	Description
`Paddle-Signature`	Signature with timestamp and HMAC hash (ts=...;h1=...)
`Content-Type`	Always application/json

Paddle webhook payload structure

Paddle Billing sends a consistent JSON payload structure:

Field	Description
`event_id`	Unique identifier for this event
`event_type`	The event type (e.g., subscription.created)
`occurred_at`	ISO 8601 timestamp of when the event occurred
`data`	The full resource object affected by the event

Testing the integration

Paddle provides tools for testing webhooks:

Use the Paddle Sandbox environment for testing
Create a test subscription using the Paddle.js checkout in sandbox mode
Use the "Simulate" button next to your notification destination to send test events
Check your HookWatch Events page to see the events

Tip

Paddle sandbox and production environments use different API keys and webhook secrets. Make sure you're using the correct credentials for each environment.

Common issues

Signature verification fails

Make sure you're correctly parsing the Paddle-Signature header format. The signed payload is the timestamp concatenated with a colon and the raw request body.

Sandbox vs. production events

Sandbox and production use separate notification destinations. Events from sandbox won't appear in your production webhook, and vice versa.

Missing event types

Make sure you've subscribed to the specific event types you need in the notification destination settings. Paddle doesn't send events you haven't explicitly subscribed to.