PayPal webhooks
PayPal webhooks are HTTPS POST requests that PayPal sends to a URL you subscribe on an app, telling you about payments, subscriptions, disputes and other events on that app.
How PayPal webhooks work
Webhooks tell you about things your own system didn't start, such as a subscription processing each cycle, a refund issued from the paypal.com business dashboard, or a redirected buyer approving a payment. A listener URL belongs to one app and only receives that app's events, so payments on a second REST app on the same account won't reach it. PayPal posts each event to every URL subscribed to it.
Each delivery is a JSON body. event_type names the event, such as PAYMENT.CAPTURE.COMPLETED, resource holds the object it happened to, and resource_type says what kind of object that is. Many bodies also carry resource_version, because the same event can come from different versions of an API. Webhooks are separate from PayPal's older Instant Payment Notifications, which have a different validation model.
Key facts
paypal-transmission-sig Also sent: paypal-transmission-id, paypal-transmission-time, paypal-cert-url, paypal-auth-algo.
RSA, SHA-256, base64 Asymmetric: verify with the vendor's public key.
Docs discrepancy
PayPal's Invoicing webhooks page describes a different signed string, with a SHA-256 hex digest of the body and a hex signature, and its Expanded Checkout best practices page says to verify HMAC signatures. Follow the integration guide's CRC32 and base64 scheme, which is what PayPal's signatures match.
Docs ↗{paypal-transmission-id}|{paypal-transmission-time}|{webhook ID}|{CRC32 of raw body} The two header values as sent, your listener URL's Webhook ID, and the CRC32 of the raw body in decimal, joined by pipes with no spaces.
cal_poolstack, client_pid, correlation-id, paypal-auth-algo, paypal-auth-version, paypal-cert-url, paypal-transmission-id, paypal-transmission-time, x-b3-spanid id, event_version, create_time, resource_type, resource_version, event_type, summary, resource, links Setting up PayPal webhooks
- Subscribe a listener URL under your app's settings in Application management, or with
POST /v1/notifications/webhooks, and record its Webhook ID. PayPal only delivers to HTTPS on port 443. - Choose event types for each URL, or use
*for all of them. An app can have up to 10 URLs. - Test with the Webhooks simulator, which posts mock events to your listener, then with real events from a sandbox app. To receive them on your own machine, use the Hookdeck CLI.
- Resend an event from the Webhooks Events dashboard, which covers the last 30 days, or with
POST /v1/notifications/webhooks-events/{event_id}/resend. Simulator events can't be resent.
Delivery behaviour
5 to 10 seconds from PayPal's Expanded Checkout best practices; its Invoicing webhooks page says 30 seconds Retries up to 25 over 3 days with exponential backoff, after a non-2xx or no connection After retries marked Failed resend by hand from the Webhooks Events dashboard Ordering not guaranteed delays and retries can put a later event first Known failure modes
From Hookdeck's PayPal guide →-
Duplicate deliveries
PayPal uses at-least-once delivery, so the same event can arrive more than once with the same
Handle duplicates →id. Deduplicate onidbefore you process it. -
Out-of-order delivery
PayPal doesn't guarantee delivery order, so an invoice's
Handle ordering →PAIDevent can arrive before itsSENTevent. Fetch the resource's current state from the API when order matters. -
Deliveries stop after an outage
PayPal retries for 3 days, then marks the delivery Failed. Its Invoicing webhooks page adds that 100 or more consecutive failures disable the endpoint until you re-enable it in the dashboard.
Retries and disabled endpoints → -
Simulator events fail postback verification
PayPal's verify-webhook-signature API doesn't support Webhooks simulator events. Verify them yourself, using the literal string
Testing with the simulator →WEBHOOK_IDas the Webhook ID.
PayPal webhook best practices
- Verify every signature.
Without it you can't tell that a delivery came from PayPal. Check that
paypal-cert-urlis on paypal.com before you fetch it, because a forged request sets that header too. - Return a 2xx quickly. Respond before any complex logic and process the event in the background, so a slow handler doesn't turn into retries.
- Deduplicate on the event id.
PayPal delivers at least once. Store each
idwith a unique constraint before you act on the event. - Fetch current state when order matters. Events can arrive out of order, so read the resource from the API rather than trusting arrival order.
- Subscribe only to events you process.
A
*subscription also picks up new event types as PayPal adds them, and your handler has to accept and discard all of them. - Reconcile after an outage.
PayPal stops after 3 days. List what you missed with
GET /v1/notifications/webhooks-eventsand resend it.
Common PayPal webhook events
Payments
CHECKOUT.ORDER.APPROVED | Buyer approves an order, ready for you to capture |
PAYMENT.CAPTURE.COMPLETED | Capture finishes and the order can be fulfilled |
PAYMENT.CAPTURE.DENIED | Capture gets denied, so stop fulfilment |
PAYMENT.CAPTURE.PENDING | Capture moves to pending, so don't fulfil yet |
PAYMENT.CAPTURE.REFUNDED | Merchant refunds captured funds |
Subscriptions
BILLING.SUBSCRIPTION.ACTIVATED | Subscription becomes active |
BILLING.SUBSCRIPTION.CANCELLED | Subscription or billing agreement gets cancelled |
BILLING.SUBSCRIPTION.PAYMENT.FAILED | Subscription payment attempt fails |
PAYMENT.SALE.COMPLETED | Sale completes, including each subscription payment |
Disputes
CUSTOMER.DISPUTE.CREATED | New dispute is opened |
CUSTOMER.DISPUTE.UPDATED | Dispute details change |
CUSTOMER.DISPUTE.RESOLVED | Dispute reaches a resolution |
Events by resource
| Resource | Events | Payloads |
|---|---|---|
merchant_account | 19 | 1 |
subscription | 16 | 14 |
payout | 13 | 0 |
payment | 10 | 4 |
invoice | 9 | 0 |
payment_token | 9 | 1 |
checkout | 8 | 6 |
sale | 5 | 1 |
dispute | 4 | 1 |
1 more resource, including Other PayPal events. All 96 events →
In this hub
| Webhook events → | Every covered PayPal event, with payloads where the registry has them. |
| MCP events → | How an agent subscribes to PayPal events as MCP events. |
| Verify signatures → | Signature facts, verification code and common failures. |
| Production guide → | Production problems: timeouts, duplicates, ordering and retries, and how to handle them. |
| Agent skill → | Install the webhook skill in your coding agent. npx skills add hookdeck/webhook-skills --skill paypal-webhooks |
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.