Handle webhook delivery

Build a production-ready webhook handler that receives Paddle events reliably. Ask me which language and framework I'm using (e.g. Node.js/Express, Python/FastAPI, Next.js API routes, Go, Ruby/Rails), then generate a complete handler that: 1. Listens for POST requests at a path I choose (e.g. /api/webhook) 2. Reads the raw request body as bytes — do not parse it first. Signature verification requires the raw body exactly as received 3. Verifies the Paddle-Signature header using my endpoint_secret_key (prefixed pdl_ntfset_). Use the Paddle SDK's unmarshal or verify method if available for my language — it handles timestamp validation too. For full details on verification, fetch https://developer.paddle.com/webhooks/signature-verification.md or use the paddle-docs MCP server 4. Returns HTTP 200 immediately — before doing any processing. Five seconds is the hard deadline; if my server doesn't respond in time, Paddle treats the delivery as failed and will retry 5. Queues the verified event payload for async processing (use an in-memory queue, background job, message broker, or database queue depending on my stack) 6. In the async processor, checks occurred_at on the event before applying changes — Paddle cannot guarantee delivery order, so a later event may arrive before an earlier one 7. Stores processed event IDs to prevent duplicate side effects (idempotency) — Paddle may deliver the same event more than once due to retries Also add a comment noting the Paddle IP addresses that should be added to my server's allowlist: - Sandbox: 34.194.127.46, 54.234.237.108, 3.208.120.145, 44.226.236.210, 44.241.183.62, 100.20.172.113 - Live: 34.232.58.13, 34.195.105.136, 34.237.3.244, 35.155.119.135, 52.11.166.252, 34.212.5.7 For full details, fetch https://developer.paddle.com/webhooks/respond-to-webhooks.md or use the paddle-docs MCP server. Ask me for my framework, the webhook endpoint path I want to use, and where my endpoint_secret_key is stored (e.g. environment variable name), then generate the complete handler code.

Diagnose why my webhook handler isn't receiving Paddle events, or is receiving them inconsistently. Work through the following checks in order, using the Paddle MCP server tools where available: 1. Check the notification destination is active and configured correctly Use get_notification_setting (or list_notification_settings) to confirm the destination has active: true and is subscribed to the events I'm expecting. A destination with active: false won't receive any webhooks. 2. Find failing notifications and inspect delivery logs Use list_notifications and filter by status "failed" or "needs_retry" to find deliveries that aren't succeeding. Then use list_notification_logs with the notification ID (prefixed ntf_) to see the HTTP response codes and response bodies my server returned. Common patterns: - 5xx errors: my server is crashing or throwing an unhandled exception - No response / timeout: my handler is doing work before returning 200 — it should respond immediately and process asynchronously - Connection refused or 404: the URL in my notification destination is wrong, or my server isn't publicly reachable 3. Check IP allowlisting Paddle sends webhooks only from specific IP addresses. If I'm blocking unknown IPs, I need to allowlist: - Sandbox: 34.194.127.46, 54.234.237.108, 3.208.120.145, 44.226.236.210, 44.241.183.62, 100.20.172.113 - Live: 34.232.58.13, 34.195.105.136, 34.237.3.244, 35.155.119.135, 52.11.166.252, 34.212.5.7 4. Check WAF rules If I'm using a Web Application Firewall, it may be classifying Paddle's requests as bot traffic. I need a bypass rule for my webhook endpoint path that matches the Paddle IP addresses above and the user agent string "Paddle". 5. Check for serverless cold starts If I'm on Vercel, AWS Lambda, Google Cloud Functions, or similar, cold starts can cause my function to exceed the 5-second response deadline intermittently. Consider pre-warming the function or increasing the function timeout. For full details, fetch https://developer.paddle.com/webhooks/respond-to-webhooks.md or use the paddle-docs MCP server. Ask me to describe what I'm seeing — for example, no webhooks arriving at all, intermittent failures, specific HTTP error codes — then work through the relevant checks and show me the delivery logs.

Find webhook deliveries that failed and replay them to recover any events my app missed. Use the Paddle MCP server tools. If those aren't available, use the Paddle API or SDK. Steps: 1. Find failed notifications Use list_notifications filtered by status "failed" to find notifications where all delivery attempts were exhausted. Optionally pass a from and to datetime to narrow to a specific time window — for example, after an outage. Notification IDs are prefixed with ntf_. 2. Inspect delivery logs to understand what went wrong Use list_notification_logs with a notification ID to see each delivery attempt, the HTTP response code my server returned, and the response body. This helps confirm the root cause before replaying. 3. Replay failed notifications Use replay_notification with each notification ID to trigger a new delivery attempt. Paddle creates a new notification entity for the replay, linked to the same original event. The response includes the new notification_id. Important constraints: - Only notifications with a status of "failed" or "delivered" can be replayed. Notifications still in flight ("needs_retry" or "not_attempted") cannot be replayed yet — wait for them to finish first - Only original event-driven notifications can be replayed. You cannot replay a notification that was itself created by a replay - Notifications older than 90 days are not retained and cannot be replayed - Fix the root cause in my webhook handler before replaying — otherwise the replayed notifications will fail again - Make sure my handler is idempotent before replaying: processing the same event_id twice should not cause duplicate side effects. Check occurred_at to apply events in the correct order if replaying a large batch For full details, fetch https://developer.paddle.com/webhooks/respond-to-webhooks.md or use the paddle-docs MCP server. Ask me which notification destination to check and what time window to look at, then list the failed notifications, show me the delivery logs for the most recent failures, and replay the ones I confirm.