Paddle webhooks notify your application about subscription lifecycle events, payment completions, refunds, and customer updates. As a merchant of record, Paddle's webhooks are essential for managing subscription billing.
Paddle webhooks are HTTP POST requests that Paddle sends to your server when specific events occur in your account. Rather than continuously polling the Paddle API for updates, webhooks deliver real-time notifications the moment something happens — a payment completes, a user signs up, a deployment finishes, or any other tracked event.
Debugging these webhooks can be challenging because they originate from Paddle's servers, not your browser. You can't simply open DevTools to inspect them. That's where WebhookVault comes in — capture every Paddle webhook, inspect the full payload and headers, and replay them to your local development server.
| Event | Description |
|---|---|
| subscription.created | Fired when a new subscription is created |
| transaction.completed | Fired when a payment transaction is successfully completed |
| subscription.canceled | Fired when a subscription is canceled |
| adjustment.created | Fired when a refund or credit adjustment is issued |
Follow these steps to start capturing and debugging Paddle webhooks using WebhookVault.
Sign up for a free WebhookVault API key and create an endpoint to capture Paddle webhooks.
curl -X POST https://webhookvault.anethoth.com/api/v1/endpoints \
-H "Authorization: Bearer wv_your_key" \
-H "Content-Type: application/json" \
-d '{"name": "Paddle Webhooks"}'
# Response:
# {"url": "https://webhookvault.anethoth.com/hook/abc123", "inspect_url": "https://webhookvault.anethoth.com/inspect/abc123"}Go to the Paddle Dashboard > Developer Tools > Notifications Click 'New Destination' and select Webhook Enter your WebhookVault endpoint URL and select the events to subscribe to Save and copy the webhook secret key for signature verification
Once Paddle sends a webhook, you can inspect every detail through the WebhookVault API or web inspector.
curl https://webhookvault.anethoth.com/api/v1/endpoints/abc123/requests \
-H "Authorization: Bearer wv_your_key"
# Returns all captured Paddle webhook requests with full headers, body, and metadataReplay any captured Paddle webhook to your local development server for testing.
curl -X POST https://webhookvault.anethoth.com/api/v1/endpoints/abc123/requests/1/replay \
-H "Authorization: Bearer wv_your_key" \
-H "Content-Type: application/json" \
-d '{"url": "http://localhost:3000/webhook"}'
# The original Paddle webhook is replayed to your local serverHere is an example of a typical Paddle webhook payload. Use WebhookVault to capture real payloads from your Paddle account for accurate testing.
{
"event_id": "evt_01h8bjnycgpna6ddx0dqz7r4gy",
"event_type": "subscription.created",
"occurred_at": "2024-01-15T10:30:00.000000Z",
"notification_id": "ntf_01h8bjnycgpna6ddx0dqz7r4gy",
"data": {
"id": "sub_01h8bjnycgpna6ddx0dqz7r4gy",
"status": "active",
"customer_id": "ctm_01h8bjnycgpna6ddx0dqz7r4gy",
"currency_code": "USD",
"items": [
{
"price": {
"unit_price": {
"amount": "999",
"currency_code": "USD"
}
}
}
]
}
}Here are the most common issues developers encounter when working with Paddle webhooks, and how to resolve them.
Paddle Billing uses a webhook secret to sign notifications. Verify the Paddle-Signature header using the provided secret.
Paddle Classic and Paddle Billing have different webhook formats and event types. Ensure you're using the correct documentation.
Paddle sandbox and production environments have separate webhook configurations and API keys.
Paddle does not guarantee event delivery order. Use the occurred_at timestamp to determine the sequence of events.
Paddle webhooks are HTTP callbacks that Paddle sends to your server when specific events occur. Instead of polling the Paddle API for changes, webhooks push real-time notifications to your application, making your integration more efficient and responsive.
Use WebhookVault to capture Paddle webhooks in the cloud, then replay them to your localhost. Create a WebhookVault endpoint, configure Paddle to send webhooks to it, and use the replay API to forward captured requests to http://localhost:3000/webhook (or your local port).
Most webhook providers, including Paddle, sign their webhook payloads to prove authenticity. Check the Paddle documentation for the specific signature header and verification algorithm. Use WebhookVault to capture and inspect the raw headers to debug signature verification issues.
Unlike ngrok, WebhookVault captures and stores every webhook request with full headers and payloads. You can replay any Paddle webhook to your local server as many times as needed, inspect historical requests, and share webhook data with your team. No tunnel to maintain or port to expose.
Create a free WebhookVault endpoint in seconds. Capture, inspect, and replay Paddle webhooks with zero configuration.
Get Free API Key