# 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.

Agent skill: `npx skills add hookdeck/webhook-skills --skill paypal-webhooks` ([details](https://hookdeck.com/webhooks/paypal/skill))

> Independent reference generated from hookdeck/webhook-registry (commit a24c8d9, 19 Nov 2026). [PayPal's official docs](https://developer.paypal.com/docs/api/webhooks/v1/).

[Overview](https://hookdeck.com/webhooks/paypal) · [Webhook events (96)](https://hookdeck.com/webhooks/paypal/events) · [MCP events](https://hookdeck.com/webhooks/paypal/mcp-events) · [Verify signatures](https://hookdeck.com/webhooks/paypal/verify) · [Production guide](https://hookdeck.com/webhooks/paypal/guide-duplicates-ordering-retries-timeouts) · [Agent skill](https://hookdeck.com/webhooks/paypal/skill)

## Key facts

| Fact | Value | Source |
|---|---|---|
| Signature header | `paypal-transmission-sig` Also sent: paypal-transmission-id, paypal-transmission-time, paypal-cert-url, paypal-auth-algo. | [PayPal docs](https://developer.paypal.com/api/rest/webhooks/rest/) |
| Scheme | `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](https://developer.paypal.com/api/invoicing/webhooks/)) | [PayPal docs](https://developer.paypal.com/api/rest/webhooks/rest/) |
| Signed material | `{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. | [PayPal docs](https://developer.paypal.com/api/rest/webhooks/rest/) |
| How events are identified | `event_type field in the body` | [PayPal docs](https://developer.paypal.com/api/rest/webhooks/simulator/) |
| Body format | `JSON` Content type: application/json. | [PayPal docs](https://developer.paypal.com/api/rest/webhooks/) |
| API versioning | `resource_version in the body` Seen: 2.0, 3.0. | [PayPal docs](https://raw.githubusercontent.com/paypal/paypal-rest-api-specifications/7bbed782c329c1cbad4cf86091cb9c442d2accf4/openapi/notifications_webhooks_v1.json) |
| Send timestamp | `paypal-transmission-time` | [PayPal docs](https://developer.paypal.com/api/rest/webhooks/rest/) |
| Other headers | `cal_poolstack, client_pid, correlation-id, paypal-auth-algo, paypal-auth-version, paypal-cert-url, paypal-transmission-id, paypal-transmission-time, x-b3-spanid` | [Registry record](https://hookdeck.com/webhooks/paypal.json) |
| Envelope | `id, event_version, create_time, resource_type, resource_version, event_type, summary, resource, links` | [PayPal docs](https://developer.paypal.com/docs/api/webhooks/v1/) |
| Agent skill | `npx skills add hookdeck/webhook-skills --skill paypal-webhooks` | [Agent skill →](https://hookdeck.com/webhooks/paypal/skill) |

[Verify PayPal webhooks](https://hookdeck.com/webhooks/paypal/verify)

## 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.

## 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](/docs/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

- **Timeout:** 5 to 10 seconds. from PayPal's Expanded Checkout best practices; its Invoicing webhooks page says 30 seconds. [Guide](https://hookdeck.com/webhooks/paypal/guide-duplicates-ordering-retries-timeouts#timeouts)
- **Retries:** up to 25 over 3 days. with exponential backoff, after a non-2xx or no connection. [Guide](https://hookdeck.com/webhooks/paypal/guide-duplicates-ordering-retries-timeouts#retries)
- **After retries:** marked Failed. resend by hand from the Webhooks Events dashboard. [Guide](https://hookdeck.com/webhooks/paypal/guide-duplicates-ordering-retries-timeouts#retries)
- **Ordering:** not guaranteed. delays and retries can put a later event first. [Guide](https://hookdeck.com/webhooks/paypal/guide-duplicates-ordering-retries-timeouts#ordering)

## Known failure modes

1. **Duplicate deliveries.** PayPal uses at-least-once delivery, so the same event can arrive more than once with the same `id`. Deduplicate on `id` before you process it. [Handle duplicates](https://hookdeck.com/webhooks/paypal/guide-duplicates-ordering-retries-timeouts#duplicates)
2. **Out-of-order delivery.** PayPal doesn't guarantee delivery order, so an invoice's `PAID` event can arrive before its `SENT` event. Fetch the resource's current state from the API when order matters. [Handle ordering](https://hookdeck.com/webhooks/paypal/guide-duplicates-ordering-retries-timeouts#ordering)
3. **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](https://hookdeck.com/webhooks/paypal/guide-duplicates-ordering-retries-timeouts#retries)
4. **Simulator events fail postback verification.** PayPal's verify-webhook-signature API doesn't support Webhooks simulator events. Verify them yourself, using the literal string `WEBHOOK_ID` as the Webhook ID. [Testing with the simulator](https://hookdeck.com/webhooks/paypal/guide-duplicates-ordering-retries-timeouts#testing)

From [Hookdeck's PayPal guide](https://hookdeck.com/webhooks/paypal/guide-duplicates-ordering-retries-timeouts).

## PayPal webhook best practices

- **[Verify every signature](https://hookdeck.com/webhooks/paypal/verify).** Without it you can't tell that a delivery came from PayPal. Check that `paypal-cert-url` is on paypal.com before you fetch it, because a forged request sets that header too.
- **[Return a 2xx quickly](https://hookdeck.com/webhooks/paypal/guide-duplicates-ordering-retries-timeouts#timeouts).** 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](https://hookdeck.com/webhooks/paypal/guide-duplicates-ordering-retries-timeouts#duplicates).** PayPal delivers at least once. Store each `id` with a unique constraint before you act on the event.
- **[Fetch current state when order matters](https://hookdeck.com/webhooks/paypal/guide-duplicates-ordering-retries-timeouts#ordering).** Events can arrive out of order, so read the resource from the API rather than trusting arrival order.
- **[Subscribe only to events you process](https://hookdeck.com/webhooks/paypal/guide-duplicates-ordering-retries-timeouts#choosing-events).** 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](https://hookdeck.com/webhooks/paypal/guide-duplicates-ordering-retries-timeouts#retries).** PayPal stops after 3 days. List what you missed with `GET /v1/notifications/webhooks-events` and resend it.

## Common PayPal webhook events

### Payments

- [CHECKOUT.ORDER.APPROVED](https://hookdeck.com/webhooks/paypal/events#CHECKOUT.ORDER.APPROVED): Buyer approves an order, ready for you to capture
- [PAYMENT.CAPTURE.COMPLETED](https://hookdeck.com/webhooks/paypal/events#PAYMENT.CAPTURE.COMPLETED): Capture finishes and the order can be fulfilled
- [PAYMENT.CAPTURE.DENIED](https://hookdeck.com/webhooks/paypal/events#PAYMENT.CAPTURE.DENIED): Capture gets denied, so stop fulfilment
- [PAYMENT.CAPTURE.PENDING](https://hookdeck.com/webhooks/paypal/events#PAYMENT.CAPTURE.PENDING): Capture moves to pending, so don't fulfil yet
- [PAYMENT.CAPTURE.REFUNDED](https://hookdeck.com/webhooks/paypal/events#PAYMENT.CAPTURE.REFUNDED): Merchant refunds captured funds

### Subscriptions

- [BILLING.SUBSCRIPTION.ACTIVATED](https://hookdeck.com/webhooks/paypal/events#BILLING.SUBSCRIPTION.ACTIVATED): Subscription becomes active
- [BILLING.SUBSCRIPTION.CANCELLED](https://hookdeck.com/webhooks/paypal/events#BILLING.SUBSCRIPTION.CANCELLED): Subscription or billing agreement gets cancelled
- [BILLING.SUBSCRIPTION.PAYMENT.FAILED](https://hookdeck.com/webhooks/paypal/events#BILLING.SUBSCRIPTION.PAYMENT.FAILED): Subscription payment attempt fails
- [PAYMENT.SALE.COMPLETED](https://hookdeck.com/webhooks/paypal/events#PAYMENT.SALE.COMPLETED): Sale completes, including each subscription payment

### Disputes

- [CUSTOMER.DISPUTE.CREATED](https://hookdeck.com/webhooks/paypal/events#CUSTOMER.DISPUTE.CREATED): New dispute is opened
- [CUSTOMER.DISPUTE.UPDATED](https://hookdeck.com/webhooks/paypal/events#CUSTOMER.DISPUTE.UPDATED): Dispute details change
- [CUSTOMER.DISPUTE.RESOLVED](https://hookdeck.com/webhooks/paypal/events#CUSTOMER.DISPUTE.RESOLVED): Dispute reaches a resolution

## Events by resource

| Resource | Events | Payloads |
|---|---|---|
| [merchant_account](https://hookdeck.com/webhooks/paypal/events#resource-merchant-account) | 19 | 1 |
| [subscription](https://hookdeck.com/webhooks/paypal/events#resource-subscription) | 16 | 14 |
| [payout](https://hookdeck.com/webhooks/paypal/events#resource-payout) | 13 | 0 |
| [payment](https://hookdeck.com/webhooks/paypal/events#resource-payment) | 10 | 4 |
| [invoice](https://hookdeck.com/webhooks/paypal/events#resource-invoice) | 9 | 0 |
| [payment_token](https://hookdeck.com/webhooks/paypal/events#resource-payment-token) | 9 | 1 |
| [checkout](https://hookdeck.com/webhooks/paypal/events#resource-checkout) | 8 | 6 |
| [sale](https://hookdeck.com/webhooks/paypal/events#resource-sale) | 5 | 1 |
| [dispute](https://hookdeck.com/webhooks/paypal/events#resource-dispute) | 4 | 1 |

1 more resource. [All 96 events](https://hookdeck.com/webhooks/paypal/events)

## In this hub

- [Webhook events](https://hookdeck.com/webhooks/paypal/events): Every covered PayPal event, with payloads where the registry has them.
- [MCP events](https://hookdeck.com/webhooks/paypal/mcp-events): How an agent subscribes to PayPal events as MCP events.
- [Verify signatures](https://hookdeck.com/webhooks/paypal/verify): Signature facts, verification code and common failures.
- [Production guide](https://hookdeck.com/webhooks/paypal/guide-duplicates-ordering-retries-timeouts): Production problems: timeouts, duplicates, ordering and retries, and how to handle them.
- [Agent skill](https://hookdeck.com/webhooks/paypal/skill): Install the webhook skill in your coding agent. `npx skills add hookdeck/webhook-skills --skill paypal-webhooks`
---

Not affiliated with PayPal. Facts are compiled from public sources and linked inline. [View as JSON](https://hookdeck.com/webhooks/paypal.json) · [Report a correction](https://hookdeck.com/contact)
