Skip to main content

Point Paddle at your capture URL

1

Copy your capture URL

It is on Arrivals: https://in.webhooktrap.dev/c/ followed by a 12-character key.
2

Create a notification destination

In the Paddle sandbox dashboard, open Developer tools › Notifications › New destination. Paste the capture URL, pick the events you handle and save.
3

Trigger events

Use Send test notification, the webhook simulator, or a sandbox checkout.
Webhook Trap recognises a Paddle Billing delivery by its Paddle-Signature header. It takes the event type from event_type and the event id from event_id, and groups events by subscription, then transaction. Customer ids are kept for search but never link deliveries on their own.

Configure the agent

webhooktrap.yml
If you leave out secret, the agent looks for PADDLE_WEBHOOK_SECRET, the name in the Paddle pack. It is the destination’s secret key.
Your signing secret stays on your machine. webhooktrap.yml holds only the name of the environment variable (secret: env:NAME). The agent reads the value when it signs a delivery, strips every known secret variable from the environment of probe and reset commands, and refuses to write or upload a run document that contains the secret. The server learns the variable’s name, never its value.
Paddle signs <ts>:<body> with HMAC-SHA256 and sends ts=<ts>;h1=<hex> in Paddle-Signature. While a secret is rotated out the header can carry more than one h1; any one that matches is enough. The pack’s timestamp tolerance is 5 s. That is the default in Paddle’s SDKs, not a limit Paddle enforces: Paddle calls the timestamp check optional but recommended. Late sends a timestamp 65 s old, which a handler using the SDK default rejects.

What the scenarios do for Paddle

The 5 s budget comes from Paddle’s docs: respond with a 200 within five seconds. A budget: above it in webhooktrap.yml is refused as a configuration error.

Sources