PayPal Webhook Example

What is a PayPal webhook?

A PayPal webhook is an HTTP POST request that PayPal sends to a URL you registered, telling your server that something happened to a payment: a capture completed, a refund went through, a dispute was opened, a subscription was cancelled. These events happen inside PayPal, so the only way it can tell your server is to send it a request carrying the event.

How do I receive PayPal webhooks while developing on localhost?

PayPal can deliver requests only to public HTTPS URLs. A dev server on localhost is not reachable by PayPal, so nothing it sends arrives there. To make your localhost URL public, you need to install a tunnel, which is not a trivial task.

A simpler option is to use a ReqBin webhook URL. It is public, it takes whatever PayPal posts to it, and it shows you each request, as soon as it lands.

How do I connect a ReqBin webhook URL to PayPal?

1. Create a webhook URL with the ReqBin Webhook Tester and copy it.
2. In the PayPal Developer Dashboard, subscribe that URL to events:
   1. Open Apps & Credentials and select the app the payments run through.
   2. Add a webhook in the app's settings and paste the ReqBin URL as the listener address.
   3. Select the event types you want to receive, or subscribe to all of them.
3. Place your test order and read the PayPal webhook details on your inbox page.

Can I edit a caught request and send it to my own server?

Yes. On the inbox page, select any of the requests you received from PayPal and press Open in API Tester. The request opens in the ReqBin API tester with everything that arrived. Enter your URL, change what you need, and send the request to your server. To send requests to localhost or to another server on your local network, you need to add the ReqBin Google Chrome Extension to your browser using this link.

What does a PayPal webhook payload look like?

Every PayPal notification has the same envelope — id, event_type, create_time, resource_type, summary and links — around the object under resource.

{
  "id": "WH-2WR32451HC0233532-67976317FL4543714",
  "event_version": "1.0",
  "create_time": "2026-09-11T09:14:07.000Z",
  "resource_type": "capture",
  "event_type": "PAYMENT.CAPTURE.COMPLETED",
  "summary": "Payment completed for $ 49.0 USD",
  "resource": {
    "id": "8MC585209K746392H",
    "status": "COMPLETED",
    "amount": {
      "currency_code": "USD",
      "value": "49.00"
    },
    "final_capture": true,
    "create_time": "2026-09-11T09:14:05Z"
  },
  "links": [
    {
      "href": "https://api.paypal.com/v1/notifications/webhooks-events/WH-2WR32451HC0233532-67976317FL4543714",
      "rel": "self",
      "method": "GET"
    }
  ]
}

Two fields decide how you read the payload. event_type says what happened, PAYMENT.CAPTURE.COMPLETED in this example, and it is what your handler branches on. resource is the object the event is about, and its shape follows resource_type: a capture here, a refund, a dispute or a subscription for other events. The full list of types is in the PayPal webhook event reference.

What headers does PayPal add to the request?

Six, on top of the ones any POST carries:

How does PayPal sign a webhook?

Your production endpoint URL is public, so anyone who knows or guesses it can post to it. PayPal signs every notification with a certificate. PAYPAL-CERT-URL is the address of its public half, and you need to verify the signature before trusting the request.

There are two ways to check the signature. Verify it against the certificate yourself, or post the delivery's headers and body to PayPal's verify-webhook-signature endpoint.

Does PayPal retry a failed webhook?

Yes. Any status code that is not 2xx makes PayPal try again, up to 25 times over three days. After that the event waits in the Webhook Events dashboard, where you resend it by hand. The same event can arrive 25 times, so deduplicate on its id.