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.

96 events covered 21 captured samples

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

Signature header
paypal-transmission-sig

Also sent: paypal-transmission-id, paypal-transmission-time, paypal-cert-url, paypal-auth-algo.

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

How events are identified
event_type field in the body
Body format
JSON

Content type: application/json.

API versioning
resource_version in the body

Seen: 2.0, 3.0.

Send timestamp
paypal-transmission-time
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
Envelope
id, event_version, create_time, resource_type, resource_version, event_type, summary, resource, links
Agent skill
npx skills add hookdeck/webhook-skills --skill paypal-webhooks

Verify PayPal webhooks →

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

  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 →
  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 →
  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 →
  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 →

PayPal webhook best practices

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

CUSTOMER.ACCOUNT-LIMITATION.ADDED · CUSTOMER.ACCOUNT-LIMITATION.ESCALATED · CUSTOMER.ACCOUNT-LIMITATION.LIFTED · CUSTOMER.ACCOUNT-LIMITATION.UPDATED +15

19 1
subscription

BILLING.PLAN.CREATED · BILLING.PLAN.UPDATED · BILLING.PLAN.ACTIVATED · BILLING.PLAN.DEACTIVATED +12

16 14
payout

PAYMENT.PAYOUTSBATCH.DENIED · PAYMENT.PAYOUTSBATCH.PROCESSING · PAYMENT.PAYOUTSBATCH.SUCCESS · PAYMENT.PAYOUTS-ITEM.BLOCKED +9

13 0
payment

PAYMENT.AUTHORIZATION.CREATED · PAYMENT.AUTHORIZATION.VOIDED · PAYMENT.CAPTURE.COMPLETED · PAYMENT.CAPTURE.DECLINED +6

10 4
invoice

INVOICING.INVOICE.CANCELLED · INVOICING.INVOICE.CREATED · INVOICING.INVOICE.PAID · INVOICING.INVOICE.REFUNDED +5

9 0
payment_token

VAULT.PAYMENT-TOKEN.CREATED · VAULT.PAYMENT-TOKEN.DELETED · VAULT.PAYMENT-TOKEN.DELETION-INITIATED · PAYMENT-TOKENIZATION.ENROLLMENT.CREATED +5

9 1
checkout

PAYMENTS.PAYMENT.CREATED · CHECKOUT.CHECKOUT.BUYER-APPROVED · CHECKOUT.ORDER.APPROVED · CHECKOUT.ORDER.COMPLETED +4

8 6
sale

PAYMENT.SALE.COMPLETED · PAYMENT.SALE.DENIED · PAYMENT.SALE.PENDING · PAYMENT.SALE.REFUNDED +1

5 1
dispute

CUSTOMER.DISPUTE.CREATED · CUSTOMER.DISPUTE.RESOLVED · CUSTOMER.DISPUTE.UPDATED · RISK.DISPUTE.CREATED

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.

Not affiliated with PayPal. Facts are compiled from public sources and linked inline.