PayPal webhooks
Last verified against PayPal's documentation on September 27, 2026.
PayPal sends webhooks when something happens to a payment, a subscription, a dispute, or an invoice. Its signature scheme is more involved than most: an RSA signature over a string that combines the transmission ID, the timestamp, your webhook ID, and a CRC32 checksum of the body, verified with a certificate PayPal hosts. Most verification failures come from computing that checksum over a parsed body or using the wrong webhook ID. This page covers what PayPal sends, how it delivers, how to fix the common errors, and where HookDeploy fits.
What PayPal sends webhooks for
| Area | Example events | Typical use |
|---|---|---|
| Checkout and captures | CHECKOUT.ORDER.APPROVED, PAYMENT.CAPTURE.COMPLETED, PAYMENT.CAPTURE.DENIED, PAYMENT.CAPTURE.REFUNDED | Fulfill orders and record refunds |
| Subscriptions | BILLING.SUBSCRIPTION.ACTIVATED, BILLING.SUBSCRIPTION.CANCELLED, BILLING.SUBSCRIPTION.PAYMENT.FAILED | Keep access in sync |
| Disputes | CUSTOMER.DISPUTE.CREATED, CUSTOMER.DISPUTE.RESOLVED | Respond to disputes in time |
| Invoicing | INVOICING.INVOICE.PAID, INVOICING.INVOICE.CANCELLED | Track invoices |
Each webhook is a JSON POST with an event id, an event_type, a resource_type, and the affected object under resource.
How PayPal delivers webhooks
| Behavior | Detail |
|---|---|
| Method and format | POST with a JSON body, to port 443 only |
| Signature headers | PAYPAL-TRANSMISSION-ID, PAYPAL-TRANSMISSION-TIME, PAYPAL-TRANSMISSION-SIG, PAYPAL-CERT-URL, and PAYPAL-AUTH-ALGO |
| Signed message | The transmission ID, transmission time, your webhook ID, and the CRC32 of the raw body as a decimal, joined with pipe characters |
| Signature | RSA-SHA256, verified with the certificate at PAYPAL-CERT-URL |
| Alternative | The verify webhook signature API, which checks it for you in one extra call |
| Success | Any 2xx |
| Retries | Up to 25 times over 3 days |
| Deduplication | The event id |
Common PayPal webhook errors and how to fix them
Verification returns FAILURE
- Parsed body. The CRC32 is computed over the exact bytes PayPal sent. Re-serialized JSON gives a different checksum.
- Wrong webhook ID. The signed message includes the ID PayPal assigned to your webhook, and sandbox and live have different IDs.
- Simulator events. Events from the Webhooks simulator use a special webhook ID, so they never verify. Test with real sandbox transactions.
CRC32 is off
PayPal uses the unsigned CRC32 as a decimal number in the signed message. A signed integer or a hex string won’t match.
Certificate URL trust
Only download certificates from PayPal’s own hosts. Check the PAYPAL-CERT-URL host before fetching it, and cache the certificate.
Duplicate events
Retries resend the same event. Deduplicate on the event id.
Why use HookDeploy with PayPal
Capture every event
HookDeploy captures every PayPal webhook at Cloudflare’s edge and responds right away, before forwarding it to your server. If your server is down for longer than PayPal’s 3 days of retries, the events are still in HookDeploy.
- Destination retries. Starter retries 3 times (after 30 seconds, 5 minutes, and 30 minutes). Pro and Scale retry up to 5 times on a schedule you choose. Free doesn’t retry automatically.
- Incidents. Forward failures are grouped into incidents, and you can bulk-replay them once your server recovers.
- History. HookDeploy keeps captured webhooks for your plan’s retention period, from 7 days on Free to 365 days on Enterprise.
One webhook, many systems
Send each PayPal event to your app, your accounting or ERP system, and an alert channel in parallel. A failing destination doesn’t hold up the others. Free includes 1 destination per endpoint, Starter includes 5, and Pro and above are unlimited.
Deliver to systems PayPal can’t reach
The HookDeploy Agent connects outward from your network over mTLS and delivers events to a local port, so a billing or fulfillment service in a private network can receive PayPal events with no public endpoint.
Develop against real events
A tap sends a temporary copy of live PayPal events to 127.0.0.1 on your machine while production keeps receiving them.
Know the limits
- Signature headers. HookDeploy forwards the
PAYPAL-*headers and body unchanged. Don’t use a transformation on a destination that verifies the signature. - Plan limits. On Free, requests beyond the monthly allowance or the daily limit get a
429, which PayPal treats as a failed delivery. Paid plans keep accepting traffic past the included volume.
Retries, replays, and duplicates
PayPal’s signature includes a transmission time, but the verification doesn’t reject old messages by default. HookDeploy forwards the body and every PAYPAL-* header unchanged, so retries and replays verify like the original delivery, as long as the stored body wasn’t changed by a privacy filter.
PayPal’s retries, HookDeploy’s retries, and replays can all deliver the same event. Deduplicate on the event id.
Set up PayPal with HookDeploy
- In HookDeploy, create an endpoint (for example,
PayPal live) and copy its URL. - On the Forwarding tab, add a destination pointing to your handler, or to an agent for private delivery, and set its retries.
- In the PayPal Developer Dashboard, open your app, add a webhook with your HookDeploy URL, and choose your event types. Copy the webhook ID.
- Run a real sandbox transaction, and confirm the event appears in HookDeploy and reaches your handler.
Example handler (Node.js and Express)
import crypto from 'node:crypto';
import express from 'express';
import crc32 from 'buffer-crc32';
const app = express();
const certCache = new Map();
async function getCert(url) {
const { protocol, hostname } = new URL(url);
if (protocol !== 'https:' || !hostname.endsWith('.paypal.com')) throw new Error('Untrusted cert URL');
if (!certCache.has(url)) certCache.set(url, await (await fetch(url)).text());
return certCache.get(url);
}
// Raw body parser on this route, registered before any global JSON middleware.
app.post('/webhooks/paypal', express.raw({ type: 'application/json' }), async (req, res) => {
const crc = parseInt(crc32(req.body).toString('hex'), 16); // unsigned, as a decimal
const message = `${req.get('paypal-transmission-id')}|${req.get('paypal-transmission-time')}|${process.env.PAYPAL_WEBHOOK_ID}|${crc}`;
let valid = false;
try {
const cert = await getCert(req.get('paypal-cert-url') ?? '');
valid = crypto.createVerify('SHA256').update(message)
.verify(cert, Buffer.from(req.get('paypal-transmission-sig') ?? '', 'base64'));
} catch {}
if (!valid) return res.status(401).send('Invalid signature');
res.sendStatus(200);
const event = JSON.parse(req.body.toString('utf8'));
await enqueue({ eventId: event.id, type: event.event_type, resource: event.resource });
// Deduplicate on eventId in your worker.
});
FAQ
How is a PayPal webhook signature verified?
PayPal signs a pipe-separated string of the transmission ID, transmission time, your webhook ID, and the CRC32 of the raw body. Verify the PAYPAL-TRANSMISSION-SIG against that string with the certificate from PAYPAL-CERT-URL, or call the verify webhook signature API instead.
Why does PayPal signature verification fail?
The usual causes are computing the CRC32 over a parsed body, using the webhook ID from the other environment, or testing with simulator events, which never verify because they use a special webhook ID.
How many times does PayPal retry a webhook?
Up to 25 times over 3 days, when there's no response, PayPal can't connect, or your server returns an error.
Can I use PayPal's verify webhook signature API?
Yes. It checks the signature for you in one extra API call, with the same headers and your webhook ID. Offline verification with the certificate avoids the extra call and works during PayPal API slowdowns.
How do I deduplicate PayPal webhooks?
Use the event id, which stays the same across retries of the same event.
Does HookDeploy break PayPal signature verification?
No. HookDeploy forwards the body and all PAYPAL-* headers unchanged, and PayPal's verification doesn't reject old transmission times, so first deliveries, retries, and replays all verify.