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.
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
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.<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
- Verify webhook signatures: header format, signed payload, SDK tolerance, rotation.
- Respond to webhooks: five-second limit, retry schedule, duplicates, ordering.