Щоб протестувати вебхуки ізольованого програмного середовища PayPal на локальному хості, запустіть свій слухач локально, відкрийте його маршрут через загальнодоступний тунель HTTPS, зареєструйте цю URL-адресу в програмі ізольованого програмного середовища та запустіть або реальну транзакцію ізольованого програмного середовища, або імітаційну подію в Симуляторі вебхуків PayPal. Зберегти увімкнено перевірку підпису: події симулятора та події, пов’язані з програмою, мають важливу різницю під час перевірки, пояснену нижче.
Чому PayPal не може надсилати безпосередньо на localhost
PayPal доставляє сповіщення про вебхук зі своїх власних серверів. Така адреса, як http://localhost:3000/api/paypal, вказує на машину PayPal з точки зору PayPal, а не з вашої. localhost tunnel надає локальному процесу загальнодоступну адресу HTTPS, залишаючи програму на вашому комп’ютері.
В офіційній документації PayPal Webhooks Simulator зазначено, що його слухач має бути доступним через HTTPS на порту 443. Тунель обробляє цю загальнодоступну кінцеву точку TLS і пересилає запит на будь-який локальний порт, наприклад 3000 або 8080.
Виберіть правильний тестовий шлях PayPal
Макет симулятора подій для розвитку слухача
Симулятор може надсилати репрезентативні події, зокрема реєстрацію платежів, відшкодування та виставлення рахунків, без створення транзакції. Це найшвидший спосіб підтвердити маршрутизацію, розбір JSON, коди відповідей і відправку подій. Фальшиві події не прив’язані до програми REST, не відображаються в засобі перегляду подій вебхуку програми, не можуть бути повторно надіслані та не представляють реальні транзакції.
Реальні події PayPal Sandbox для наскрізної поведінки
Для реалістичної інтеграції створіть програму REST на інформаційній панелі розробника PayPal, додайте кінцеву точку тунелю як вебхук, виберіть необхідні типи подій і виконайте перевірку ізольованого програмного середовища або операцію API. Ці події належать програмі ізольованого програмного середовища та використовують ті самі облікові дані програми, ідентифікатор вебхуку, засіб перегляду подій і робочий процес повторного надсилання, які ви використовуватимете перед створенням.
Налаштувати вебхук PayPal на локальному хості
- Запустіть свою програму та переконайтеся, що маршрут працює локально:
curl -i -X POST http://localhost:3000/api/webhooks/paypal -H 'content-type: application/json' -d '{"event_type":"LOCAL.PING"}'. - Запустіть
npx portpreview 3000та скопіюйте згенеровану URL-адресу HTTPS. - Створіть повний зворотний виклик, наприклад
https://your-subdomain.portpreview.dev/api/webhooks/paypal. - Для імітаційного тестування вставте його в симулятор Webhooks і виберіть подію. Для тестування додатка додайте його в налаштуваннях вебхуку програми REST ізольованого програмного середовища.
- Надіслати подію та перевірити вхідний метод, заголовки PayPal, необроблений текст, журнали обробника та відповідь HTTP.
Підписуйтеся лише на події, які обробляє ваша програма. Широка підписка створює шум і полегшує випадковий запуск бізнес-логіки для події, яку ви ніколи не моделювали.
A practical Express listener
import express from 'express';
const app = express();
app.use(express.json({ verify: (req, _res, buf) => {
req.rawBody = Buffer.from(buf);
}}));
app.post('/api/webhooks/paypal', async (req, res) => {
const event = req.body;
// Verify first; do not fulfill an order from untrusted JSON.
const verified = await verifyPayPal(req.headers, event);
if (!verified) return res.status(401).send('invalid signature');
// Claim the event ID atomically so retries cannot duplicate work.
const firstDelivery = await claimEvent(event.id);
if (!firstDelivery) return res.sendStatus(200);
if (event.event_type === 'PAYMENT.CAPTURE.COMPLETED') {
await markOrderPaid(event.resource.id);
}
return res.sendStatus(200);
});
app.listen(3000);Зробіть підтвердження коротким. Зберігайте подію, повертайте відповідь 2xx і виконуйте повільну електронну пошту або роботу в черзі. Ідентифікатор події є природним ключем ідемпотентності; застосувати унікальне обмеження бази даних, а не покладатися на набір у пам’яті.
Правильно перевірте підписи PayPal
PayPal надсилає метадані передачі в заголовках, зокрема PAYPAL-AUTH-ALGO, PAYPAL-CERT-URL, PAYPAL-TRANSMISSION-ID, PAYPAL-TRANSMISSION-SIG та PAYPAL-TRANSMISSION-TIME. Для подій, пов’язаних із програмою, ви можете надіслати ці значення, ідентифікатор вебхуку та подію в API PayPal Sandbox /v1/notifications/verify-webhook-signature. Успішної відповіді HTTP недостатньо; потрібно, щоб verification_status дорівнював SUCCESS. PayPal також документує локальну криптографічну перевірку у своєму посібнику з інтеграції webhook.
Застереження щодо симулятора: Кінцева точка перевірки зворотного зв’язку PayPal не підтримує фіктивні події симулятора. PayPal документує літеральний ідентифікатор вебхуку WEBHOOK_ID для самоперевірки підпису симулятора. Не плутайте це спеціальне значення зі справжнім ідентифікатором вебхуку, призначеним програмі ізольованого програмного середовища. Якщо вашою найближчою метою є тестування самого API зворотного зв’язку, згенеруйте фактичну транзакцію ізольованого програмного середовища замість імітаційної події симулятора.
Перед завантаженням переконайтеся, що URL-адреса будь-якого сертифіката відповідає задокументованим правилам PayPal, зберігайте точне представлення подій, яке вимагає метод перевірки, і ніколи не реєструйте маркери доступу, секрети клієнта, підписи чи повні платіжні дані.
Тестуйте події, які змінюють гроші або доступ
PAYMENT.CAPTURE.COMPLETED: дозволити виконання лише після перевірки очікуваних ідентифікаторів замовлення, суми, валюти та статусу захоплення.PAYMENT.CAPTURE.REFUNDED: безпечно скасовувати права та підтримувати часткове відшкодування.- Події оформлення замовлення: відрізнити схвалення від завершеного захоплення; лише схвалення не є доказом того, що кошти були захоплені.
- Події підписки: тестова активація, призупинення, скасування, невдалий платіж і доставка поза замовленням на ваш платіжний стан.
Події постачальника — це сповіщення, а не безсумнівні команди бази даних. Для конфіденційних переходів отримайте посилання на ресурс PayPal із автентифікованими обліковими даними API та порівняйте його з вашим власним записом замовлення.
Усунення несправностей локальної доставки
Симулятор не може підключитися
Підтвердьте, що URL-адреса починається з https://, містить точний шлях вебхуку та все ще вказує на запущений тунель. Перевірте публічну URL-адресу самостійно за допомогою curl. 404 зазвичай означає, що шлях або маршрут фреймворку неправильний; 502 зазвичай означає, що тунель не може досягти локального процесу.
Обробник повертає 401
Спочатку визначте, чи надійшла подія з симулятора чи зареєстрованої програми ізольованого середовища. Перевірте відповідний ідентифікатор вебхука та метод підтвердження. Потім переконайтеся, що проксі-сервери зберегли всі заголовки PAYPAL-* і що ви не змішуєте активні облікові дані з api-m.sandbox.paypal.com.
PayPal повторює спробу або позначає доставку як помилку
Повернути 2xx лише після того, як подія буде довгостроково прийнята. Уникайте переспрямувань, сторінок помилок HTML, проміжного програмного забезпечення автентифікації та довгих синхронних завдань на маршруті. Використовуйте засіб перегляду подій для реальних подій програми та результати симулятора для діагностики імітації доставки. Перегляньте посібник із повторних спроб і ідемпотентності, щоб дізнатися про стійкі шаблони обробки.
Перевірка безпеки перед запуском
- Використовуйте окрему PayPal Sandbox та активні облікові дані клієнта, ідентифікатори вебхуків і секрети кінцевих точок.
- Перевірте кожен підпис перед аналізом бізнес-полів або зміною стану.
- Видалити дублікат за ідентифікатором події PayPal і зробити транзакції виконання атомарними.
- Дозволити лише
POST, обмежити розмір запиту, застосувати обмеження швидкості та зберегти URL-адресу тунелю закритою, коли це можливо. - Редагувати дані покупця та облікові дані з журналів; обертати все, що було відкрито під час налагодження.
- Замініть URL-адресу тимчасового тунелю на стабільну робочу кінцеву точку та повторіть перевірку підпису та повторіть спробу.
Щоб отримати повні схеми подій і перевірки, скористайтеся основним довідником API Webhooks PayPal. Щоб отримати незалежну від фреймворка інформацію про необроблені тіла та безпечні порівняння, прочитайте посібник із перевірки підпису вебхука.