PayPal webhooks in production: duplicates, ordering, retries and timeouts
This guide covers the problems PayPal webhooks cause in production and how to handle each one. What PayPal sends and how it's signed is on the PayPal webhooks overview, every event type is on PayPal webhook events, and signature verification code is on Verify PayPal webhooks.
At a glance
| Problem | What to do | With Event Gateway |
|---|---|---|
| Timeouts | Return a 2xx within 5 to 10 seconds; process in a background job | Accepts the delivery at once, then queues it for your service |
| Duplicates | Record processed event ids; make handlers idempotent | Drops repeats before they reach your handler |
| Ordering | Fetch current state; don't assume arrival order | Logs every event and attempt, so you can see arrival order when debugging |
| Retries | Stay available; reconcile and resend after an outage | Accepts deliveries while your service is down and replays them |
| Choosing events | Subscribe only to the events you process | Filters and routes events by type |
| Testing | Use the simulator, then sandbox events, then forward to localhost | Forwards to localhost and replays past events |
| Other limits | Plan for 10 URLs per app, app-scoped events, port 443 and spikes | Fans one URL out to many destinations at a rate you set |
PayPal webhook timeouts and slow handlers
Return a 2xx status within 5 to 10 seconds, then do the work in a background job.
Why it happens: PayPal treats no response as a failed delivery and retries it. Its docs don't agree on the limit: the Expanded Checkout best practices ask for a 2xx within 5 to 10 seconds, and the Invoicing webhooks page says 30 seconds. Its main webhook guide gives no number, so build to the shorter one. Handlers that write to a database or call other APIs before responding are the usual cause.
Fix it in your handler:
- Verify the signature and return 200 straight away.
- Push the event onto a queue (SQS, RabbitMQ or Redis) and process it in a worker. See why to process webhooks asynchronously.
- If you verify with PayPal's postback API, remember that it puts a call to PayPal inside your response time. Verifying yourself avoids that, which is why PayPal prefers it.
- Check any reverse proxy's timeout. PayPal's Invoicing page recommends 60 seconds or more.
With Event Gateway: Hookdeck accepts each PayPal delivery immediately, then queues events and delivers them to your service at a rate it can handle, with its own retries. Your handler can take as long as it needs without failing a PayPal delivery.
Duplicate PayPal webhooks
PayPal can deliver the same event more than once. Record each event id you process and skip repeats.
Why it happens: PayPal uses at-least-once delivery. Its docs list network timeouts, retries after temporary errors, load balancer duplication and slow acknowledgements as causes, and say that the same event, with the same id and create_time, can arrive several times over several minutes. Your endpoint may also process an event and then fail before it returns a 2xx, so PayPal sends it again.
Fix it in your handler:
- Track processed event ids, using a database table with a unique constraint on the id.
- Make every handler idempotent: the same result however many times it runs.
- Wrap the side effect and the id record in one transaction.
async function processPayPalEvent(event) {
const eventId = event.id;
// Check if already processed
const exists = await redis.get(`processed:${eventId}`);
if (exists) {
console.log(`Event ${eventId} already processed, skipping`);
return;
}
// Process the event
await handleEvent(event);
// Mark as processed with a TTL
await redis.setex(`processed:${eventId}`, 86400 * 7, '1'); // 7-day TTL
}
With Event Gateway: Hookdeck deduplicates events before they reach your endpoint, so repeats are filtered at the infrastructure level rather than in each handler.
Out-of-order PayPal webhooks
PayPal doesn't guarantee delivery order. Rely on the resource's current state, not on arrival order.
Why it happens: PayPal names network delays, events generated in quick succession and retries of failed deliveries as causes. Its example is an invoice's PAID event arriving before its SENT event. A retried event can arrive well after newer ones, since retries run for up to 3 days. For more on the general problem, see Webhook Ordering: Why It's Hard and How to Handle It.
Fix it in your handler:
- Don't assume event order. When order matters, fetch the current state from the PayPal API, using the resource's
idor itslinks. - Write state transitions that tolerate events in any order, so an older event can't overwrite newer state.
- Fulfil an order only when you've confirmed the capture completed. PayPal also sends
PAYMENT.CAPTURE.PENDING, which means payment isn't finished.
With Event Gateway: Hookdeck logs every event and delivery attempt, so when state looks wrong you can see the order events actually arrived in and replay them.
PayPal webhook retries and disabled endpoints
PayPal retries a failed delivery up to 25 times over 3 days, then marks it Failed and stops. Keep the endpoint available and reconcile after any outage.
Why it happens: A non-2xx status, no response and a failed connection all count as failures. PayPal retries with exponential backoff, and its docs don't give the intervals, so a retry can arrive at any point in those 3 days. After that you have to resend by hand. PayPal's Invoicing webhooks page adds that it disables an endpoint after 100 or more consecutive failures, and that you need to re-enable it in the dashboard once the problem is fixed. That page is the only one that says so.
Fix it in your handler:
- Monitor the Webhooks Events dashboard, where received events show a green check mark and pending ones a yellow exclamation point. You can filter by app, resource and event type across the last 30 days, and resend from the list.
- After an outage, list what you missed with
GET /v1/notifications/webhooks-eventsand resend it withPOST /v1/notifications/webhooks-events/{event_. PayPal doesn't resend notifications that are still pending this way.id}/resend - Run periodic reconciliation against PayPal's own APIs, such as Orders, so a missed event doesn't leave an order unfulfilled.
- If deliveries stop altogether, check that the webhook is still enabled in the dashboard.
With Event Gateway: Hookdeck captures every PayPal delivery while your services are down, so PayPal's deliveries succeed and its retries don't run out. Failed events can be retried automatically, manually or in bulk once you recover, and ones that keep failing wait in a dead letter queue.
Choosing which PayPal events to listen to
Subscribe each URL only to the events your integration processes, not to all events (*).
Why it matters: Every extra event type is a request your server has to accept, verify and discard, and * also adds new event types as PayPal introduces them. The full list, with sample payloads where we have them, is on PayPal webhook events. Some names are shared across surfaces: the deprecated billing plans and agreements webhooks use the same BILLING.PLAN and BILLING.SUBSCRIPTION names as the current Subscriptions API, and the payments events cover both versions of the Payments API.
Fix it in your handler:
- List the events your code handles and subscribe to exactly those. For alternative payment methods on the Orders API, PayPal names
CHECKOUT.ORDER.APPROVED,CHECKOUT.PAYMENT-APPROVAL.REVERSED,PAYMENT.CAPTURE.PENDING,PAYMENT.CAPTURE.COMPLETEDandPAYMENT.CAPTURE.DENIED. - Use separate URLs for sandbox and live apps, each with its own Webhook ID, so test events can't touch production data.
- Read
resource_versionbefore you parseresource, and ignore event types your handler doesn't expect.
With Event Gateway: Hookdeck filters and routes events by type or any other property, so one PayPal URL can feed several services.
Testing and debugging PayPal webhooks locally
Start with the Webhooks simulator, then move to real events from a sandbox app, forwarded to your machine with a CLI.
Why it matters: PayPal only delivers to a public HTTPS URL on port 443, and development machines sit behind NAT and firewalls. The simulator is quick, but its events are mock data. They belong to no app, so they don't appear in the dashboard, can't be resent and don't match any real transaction.
Do this:
- Send mock events from the Webhooks simulator to check that your listener receives and verifies them. Use the literal string
WEBHOOK_IDas the Webhook ID when you verify. The postback API doesn't work for these events, so test that path with sandbox events. - Subscribe your URL to a sandbox REST app and run real transactions, such as a subscription payment that produces
PAYMENT.SALE.COMPLETED. - Inspect real payloads before you write a handler. PayPal webhook events has samples to start from.
- Keep verification on in development, so the code path you test is the one you ship.
With Event Gateway: The Hookdeck CLI gives you a stable public URL to register with PayPal and forwards events to your machine, and you can replay past events without new transactions. See how to test PayPal webhooks locally.
Other PayPal webhook limits
Plan for PayPal's URL limit, app-scoped events, its network requirements and traffic spikes before they reach production.
10 URLs per app. Applications that route event types to separate services can run out. Send everything to one receiver and route internally, or create more REST apps, which adds its own management work.
Events are scoped to the app. Payments on one REST app don't generate events for webhooks on another app on the same account. Legacy NVP/SOAP payments go to the special NVP/SOAP webhooks app, and a webhook lookup can tie events that aren't tied to an app, such as payments made on PayPal.com, to the REST app you choose.
No events from before you subscribed. PayPal starts sending once a URL is subscribed. To backfill a new integration, read history from PayPal's APIs, and subscribe as early as you can.
Port 443 and blocked domains. If PayPal can't connect at all, the common causes are a firewall blocking port 443 or a domain that URL filtering services mark as abusive. PayPal suggests checking the domain at urlfiltering.paloaltonetworks.com and requesting recategorization or using another domain.
Batch payouts. PAYMENT.PAYOUTSBATCH webhooks don't include item details. Use the links in the event to fetch them.
Traffic spikes. PayPal generates events as subscriptions process, so subscriptions that share a billing date produce events together. Buffer them in a queue and scale workers horizontally.
With Event Gateway: Hookdeck sends one PayPal URL's events to as many destinations as you need, absorbs spikes in its queue and delivers at a rate you configure.
Don't lose PayPal events when your endpoint is down for days.
Hookdeck Event Gateway accepts every PayPal delivery, verifies its signature, queues events and retries to your service on your schedule.