REST APIs
    Get Started with PayPal REST APIs
    Authentication
    Postman Guide
    API requests
    API responses
    Core Resources
    Overview
    API Integration
    Release Notes
    Add Tracking
    Catalog Products
    Disputes
    Identity
    Invoicing
    Orders
    Partner Referrals
    Payment Experience
    Payment Method Tokens
    Payments
    Payouts
    Referenced Payouts
    Subscriptions
    Transaction Search
    Webhooks Management
    Webhooks
    Overview
    Webhook event names
    Webhooks Events dashboard
    Webhooks simulator
    Integration
    Sandbox
    Overview
    Accounts
    Bulk Accounts
    Card testing
    Codespaces
    PayPal for Visual Studio Code
    Negative Testing
    Go Live
    Production Environment
    PayPal Application Guidelines
    PayPal Security Guidelines
    Rate Limiting Guidelines
    Idempotency
    Troubleshooting
    Not authorized
    Resource not found
    Unprocessable entity
    Validation error
    Reference
    Currency Codes
    Country Codes
    State & Province Codes
    Locale codes
    Deprecated Resources
    Deprecated resources
    Billing Agreements
    Billing Plans
    Invoicing v1
    Orders v1
    Partner Referrals v1
    Payments v1

Webhooks guide

Overview

Webhooks are HTTPS posts from PayPal to an endpoint on your server whenever the corresponding event type occurs (see: Webhook event names). They can be thought of as an API call in the reverse direction: instead of your system calling PayPal, PayPal is making a callback to your server. This is especially useful to receive notifications of events that are triggered external to your system, such as for example: a subscription processing each cycle, a refund being initiated from the www.paypal.com business dashboard, or an alternative payment method checkout having been approved by a redirected payer and being ready for capture.

Initial configuration

The initial setup for receiving webhooks is to subscribe a listening URL for a specific app, either a REST app or possibly the NVP/SOAP webhooks app. Up to 10 webhook URLs may be subscribed per app. Specific webhook event types may be subscribed for each URL, or alternatively use * to subscribe a URL to all event types. Only events associated with the specific app will be received, so for instance payments processed on one REST app associated with an account will not generate events for webhooks subscribed to a different REST app associated with the same account. The special NVP/SOAP webhooks app only receives events for payments that result from legacy NVP/SOAP API requests (this does not include NVP/SOAP recurring payments).

Receiving and processing a webhook

Once a URL is subscribed, PayPal will begin sending messages for any subscribed event generated by the associated app (for example, if the app processes a subscription payment it will generate the event PAYMENT.SALE.COMPLETED every time). Messages for events will be posted to every subscribed listener URL. There are two steps for a listener URL to successfully handle a webhook message:

  1. Receipt of the message
  2. Verification of the message

Receiving the message

Successful receipt requires your listener endpoint to respond with an HTTP 200 or other 2xx status code. Any non-2xx status code will cause PayPal to reattempt delivery up to 25 times over the course of 3 days or until it receives a 2xx success code. If unsuccessful after 3 days, delivery will be marked as Failed (but can be resent again manually from the Webhook Events dashboard).

Successful receipt also requires PayPal to be able to connect to that listener endpoint in the first place. See: Troubleshooting delivery problems in the integration guide for more details.

Verifying the message received

There are two possible ways to verify the authenticity of a received message; either method may be used:

  1. Compute the cyclic redundancy check (CRC32) of the message and verify its signature
  2. Post the message, stored webhook ID, and header information back to PayPal’s verify signature endpoint for it to do this check for you
For details, proceed to the Integration guide.

If you do not verify a message, you will not have a way to validate that its sender was in fact PayPal.

See also

  • Webhook event names
  • Integrate webhooks
  • Webhooks API reference
Reference
PayPal.com
Privacy
Support
Legal
Contact