WebhookCatGuidesOpen your inbox

Test Paddle webhooks

Get a public URL for Paddle Billing notifications, see each event as it arrives, check its Paddle-Signature with your secret key, and forward it to your local server. Free, no signup.

Get a webhook URL

Add the URL in Paddle

  1. Open webhookcat.com, copy your URL and add /webhooks/paddle to the end. Sub-paths are kept when requests are forwarded, so this one reaches the route in the code below.
  2. In your Paddle sandbox dashboard, open Events, then Notifications, and click New destination.
  3. Choose URL as the notification type, paste your WebhookCat URL, set the usage type to Platform and simulation, pick the events and click Save destination.
  4. To send events without a real checkout, open Events, then Simulations, and click New simulation. Pick the destination and a single event or a scenario such as a subscription renewal, then run it.

What Paddle sends

Paddle-Signature
A timestamp ts= and an h1= signature, the hex HMAC-SHA256 of the timestamp, a colon and the body.
Content-Type
application/json

Check the signature

Open a request in WebhookCat and paste the secret into the Signature box under it. You'll see right away whether it matches. The check runs in your browser, and the secret is never sent or saved.

Under Notifications, open the destination's menu, choose Edit destination and copy the secret key, which starts with pdl_ntfset_. Sandbox and live accounts have separate destinations, each with its own key.

The same check in your own Node.js server:

import express from "express";
import { Paddle } from "@paddle/paddle-node-sdk";

const paddle = new Paddle(process.env.PADDLE_API_KEY);
const app = express();
// Keep the raw body: re-serialized JSON no longer matches the signature.
const raw = express.raw({ type: "application/json" });

app.post("/webhooks/paddle", raw, async (req, res) => {
  let event;
  try {
    event = await paddle.webhooks.unmarshal(
      req.body.toString(),
      process.env.PADDLE_WEBHOOK_SECRET_KEY,
      req.get("paddle-signature") ?? "",
    );
  } catch (err) {
    return res.status(400).send(err.message);
  }
  console.log(event.eventType, event.eventId);
  res.sendStatus(200);
});

Forward to your local server

In the inbox you pasted into Paddle, open Share and run the command shown there. It forwards each request to localhost:3000/webhooks/paddle with the same headers and body, so the signature check in your code passes too. Needs Node.js 22 or later.

$ npx webhookcat listen 3000 --inbox "https://webhookcat.com/#<id>/<key>"

Starting from the terminal instead? npx webhookcat listen 3000 creates a new URL and prints it. Paste that URL plus /webhooks/paddle into Paddle. More in the docs.

Good to know

  • Paddle's SDKs reject a notification signed more than 5 seconds before it reaches your server. Forwarding with the CLI gets it there in time, but a request replayed later fails that check.
  • Paddle waits 5 seconds for a 200. The sandbox retries 3 times within about 2 minutes, and live accounts keep retrying for about 2 days.
  • Simulated events have IDs that start with ntfsimevt_ instead of evt_, and only reach destinations whose usage type includes simulation.