paypal-webhooks

Name: paypal-webhooks
Author: hookdeck

80stars10forks

How to install paypal-webhooks?

hookdeck/webhook-skills/paypal-webhooks

$npx -y skills add hookdeck/webhook-skills --skill paypal-webhooks

Installs into the current project.

Summary

Receive and verify PayPal webhooks. Use when setting up PayPal webhook handlers, debugging certificate-based signature verification, or handling payment events like PAYMENT.CAPTURE.COMPLETED, PAYMENT.SALE.COMPLETED, BILLING.SUBSCRIPTION.CREATED, or CHECKOUT.ORDER.APPROVED.

Files · 1

View on GitHub

SKILL.md

1	# PayPal Webhooks
2
3	## When to Use This Skill
4
5	- Setting up PayPal webhook handlers
6	- Debugging PayPal signature verification failures (RSA-SHA256 with cert)
7	- Understanding PayPal event types like `PAYMENT.CAPTURE.COMPLETED`
8	- Handling payment, subscription, refund, or checkout events
9	- Choosing between PayPal's postback verify API and offline cert verification
10
11	## How PayPal Webhooks Differ From Most Providers
12
13	PayPal does not use HMAC with a shared secret. Instead, each webhook is
14	signed with PayPal's private key, and you verify it with the matching public
15	certificate delivered per request via the `paypal-cert-url` header. The
16	algorithm is RSA-SHA256 ("SHA256withRSA").
17
18	Two valid verification paths:
19
20	1. Postback (no crypto needed) — POST the captured headers, your
21	`webhook_id`, and the raw `webhook_event` body to PayPal's
22	`/v1/notifications/verify-webhook-signature` endpoint. Requires an OAuth
23	access token. PayPal returns `{ "verification_status": "SUCCESS" }`.
24	2. Offline self-verify (recommended for low-latency / no extra OAuth call) —
25	Fetch the cert from `paypal-cert-url` (cache it; validate the host ends with
26	`.paypal.com`), build the message
27	`transmissionId\|transmissionTime\|webhookId\|crc32(rawBody)`, and verify the
28	base64 signature against the cert's public key using RSA-SHA256.
29
30	The examples in this skill use the offline approach because it is testable
31	without OAuth and avoids an extra API call per webhook. The postback path is
32	documented in [references/verification.md](references/verification.md).
33
34	## Essential Code (USE THIS)
35
36	### Required Request Headers
37
38	\| Header \| Purpose \|
39	\|--------\|---------\|
40	\| `paypal-transmission-id` \| Unique webhook transmission ID \|
41	\| `paypal-transmission-time` \| ISO 8601 timestamp of transmission \|
42	\| `paypal-transmission-sig` \| Base64-encoded RSA-SHA256 signature \|
43	\| `paypal-cert-url` \| URL of the public cert (must be a `*.paypal.com` host) \|
44	\| `paypal-auth-algo` \| Signing algorithm, e.g. `SHA256withRSA` \|
45
46	### Signed Message Format
47
48	```
49	<transmissionId>\|<transmissionTime>\|<webhookId>\|<crc32(rawBody)>
50	```
51
52	`crc32(rawBody)` is the standard CRC-32 of the raw HTTP body as an **unsigned
53	decimal integer**. `webhookId` is the ID of the webhook registered in your
54	PayPal app (env var `PAYPAL_WEBHOOK_ID`).
55
56	### Express Webhook Handler
57
58	```javascript
59	const express = require('express');
60	const crypto = require('crypto');
61	const zlib = require('zlib');
62	const https = require('https');
63
64	const app = express();
65	const certCache = new Map();
66
67	function fetchCert(certUrl) {
68	// SECURITY: Only trust certs served from paypal.com
69	const host = new URL(certUrl).hostname;
70	if (host !== 'paypal.com' && !host.endsWith('.paypal.com')) {
71	return Promise.reject(new Error('Cert URL host is not paypal.com'));
72	}
73	if (certCache.has(certUrl)) return Promise.resolve(certCache.get(certUrl));
74	return new Promise((resolve, reject) => {
75	https.get(certUrl, (res) => {
76	let data = '';
77	res.on('data', (c) => (data += c));
78	res.on('end', () => { certCache.set(certUrl, data); resolve(data); });
79	}).on('error', reject);
80	});
81	}
82
83	async function verifyPayPalWebhook(headers, rawBody, webhookId) {
84	const transmissionId = headers['paypal-transmission-id'];
85	const transmissionTime = headers['paypal-transmission-time'];
86	const transmissionSig = headers['paypal-transmission-sig'];
87	const certUrl = headers['paypal-cert-url'];
88	if (!transmissionId \|\| !transmissionTime \|\| !transmissionSig \|\| !certUrl) {
89	return false;
90	}
91	const crc = zlib.crc32(rawBody);
92	const message = `${transmissionId}\|${transmissionTime}\|${webhookId}\|${crc}`;
93	const cert = await fetchCert(certUrl);
94	const verifier = crypto.createVerify('SHA256');
95	verifier.update(message);
96	verifier.end();
97	try {
98	return verifier.verify(cert, transmissionSig, 'base64');
99	} catch {
100	return false;
101	}
102	}
103
104	// CRITICAL: express.raw() — PayPal verification needs the raw body for CRC32
105	app.post('/webhooks/paypal',
106	express.raw({ type: 'application/json' }),
107	async (req, res) => {
108	const ok = await verifyPayPalWebhook(
109	req.headers,
110	req.body,
111	process.env.PAYPAL_WEBHOOK_ID
112	);
113	if (!ok) return res.status(400).send('Invalid signature');
114
115	const event = JSON.parse(req.body.toString('utf8'));
116	switch (event.event_type) {
117	case 'PAYMENT.CAPTURE.COMPLETED':
118	console.log('Capture completed:', event.resource.id);
119	break;
120	case 'PAYMENT.CAPTURE.REFUNDED':
121	console.log('Refund issued:', event.resou

People who liked this also viewed

6 picks

Type

paypal-webhooks

80stars10forks

View on GitHub

How to install paypal-webhooks?

hookdeck/webhook-skills/paypal-webhooks

$npx -y skills add hookdeck/webhook-skills --skill paypal-webhooks

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# PayPal Webhooks
2
3	## When to Use This Skill
4
5	- Setting up PayPal webhook handlers
6	- Debugging PayPal signature verification failures (RSA-SHA256 with cert)
7	- Understanding PayPal event types like `PAYMENT.CAPTURE.COMPLETED`
8	- Handling payment, subscription, refund, or checkout events
9	- Choosing between PayPal's postback verify API and offline cert verification
10
11	## How PayPal Webhooks Differ From Most Providers
12
13	PayPal does not use HMAC with a shared secret. Instead, each webhook is
14	signed with PayPal's private key, and you verify it with the matching public
15	certificate delivered per request via the `paypal-cert-url` header. The
16	algorithm is RSA-SHA256 ("SHA256withRSA").
17
18	Two valid verification paths:
19
20	1. Postback (no crypto needed) — POST the captured headers, your
21	`webhook_id`, and the raw `webhook_event` body to PayPal's
22	`/v1/notifications/verify-webhook-signature` endpoint. Requires an OAuth
23	access token. PayPal returns `{ "verification_status": "SUCCESS" }`.
24	2. Offline self-verify (recommended for low-latency / no extra OAuth call) —
25	Fetch the cert from `paypal-cert-url` (cache it; validate the host ends with
26	`.paypal.com`), build the message
27	`transmissionId\|transmissionTime\|webhookId\|crc32(rawBody)`, and verify the
28	base64 signature against the cert's public key using RSA-SHA256.
29
30	The examples in this skill use the offline approach because it is testable
31	without OAuth and avoids an extra API call per webhook. The postback path is
32	documented in [references/verification.md](references/verification.md).
33
34	## Essential Code (USE THIS)
35
36	### Required Request Headers
37
38	\| Header \| Purpose \|
39	\|--------\|---------\|
40	\| `paypal-transmission-id` \| Unique webhook transmission ID \|
41	\| `paypal-transmission-time` \| ISO 8601 timestamp of transmission \|
42	\| `paypal-transmission-sig` \| Base64-encoded RSA-SHA256 signature \|
43	\| `paypal-cert-url` \| URL of the public cert (must be a `*.paypal.com` host) \|
44	\| `paypal-auth-algo` \| Signing algorithm, e.g. `SHA256withRSA` \|
45
46	### Signed Message Format
47
48	```
49	<transmissionId>\|<transmissionTime>\|<webhookId>\|<crc32(rawBody)>
50	```
51
52	`crc32(rawBody)` is the standard CRC-32 of the raw HTTP body as an **unsigned
53	decimal integer**. `webhookId` is the ID of the webhook registered in your
54	PayPal app (env var `PAYPAL_WEBHOOK_ID`).
55
56	### Express Webhook Handler
57
58	```javascript
59	const express = require('express');
60	const crypto = require('crypto');
61	const zlib = require('zlib');
62	const https = require('https');
63
64	const app = express();
65	const certCache = new Map();
66
67	function fetchCert(certUrl) {
68	// SECURITY: Only trust certs served from paypal.com
69	const host = new URL(certUrl).hostname;
70	if (host !== 'paypal.com' && !host.endsWith('.paypal.com')) {
71	return Promise.reject(new Error('Cert URL host is not paypal.com'));
72	}
73	if (certCache.has(certUrl)) return Promise.resolve(certCache.get(certUrl));
74	return new Promise((resolve, reject) => {
75	https.get(certUrl, (res) => {
76	let data = '';
77	res.on('data', (c) => (data += c));
78	res.on('end', () => { certCache.set(certUrl, data); resolve(data); });
79	}).on('error', reject);
80	});
81	}
82
83	async function verifyPayPalWebhook(headers, rawBody, webhookId) {
84	const transmissionId = headers['paypal-transmission-id'];
85	const transmissionTime = headers['paypal-transmission-time'];
86	const transmissionSig = headers['paypal-transmission-sig'];
87	const certUrl = headers['paypal-cert-url'];
88	if (!transmissionId \|\| !transmissionTime \|\| !transmissionSig \|\| !certUrl) {
89	return false;
90	}
91	const crc = zlib.crc32(rawBody);
92	const message = `${transmissionId}\|${transmissionTime}\|${webhookId}\|${crc}`;
93	const cert = await fetchCert(certUrl);
94	const verifier = crypto.createVerify('SHA256');
95	verifier.update(message);
96	verifier.end();
97	try {
98	return verifier.verify(cert, transmissionSig, 'base64');
99	} catch {
100	return false;
101	}
102	}
103
104	// CRITICAL: express.raw() — PayPal verification needs the raw body for CRC32
105	app.post('/webhooks/paypal',
106	express.raw({ type: 'application/json' }),
107	async (req, res) => {
108	const ok = await verifyPayPalWebhook(
109	req.headers,
110	req.body,
111	process.env.PAYPAL_WEBHOOK_ID
112	);
113	if (!ok) return res.status(400).send('Invalid signature');
114
115	const event = JSON.parse(req.body.toString('utf8'));
116	switch (event.event_type) {
117	case 'PAYMENT.CAPTURE.COMPLETED':
118	console.log('Capture completed:', event.resource.id);
119	break;
120	case 'PAYMENT.CAPTURE.REFUNDED':
121	console.log('Refund issued:', event.resou

People who liked this also viewed

6 picks

Type