Для використання конструктора Paddle з локальним приходом, висаджувати локальний обробник через тунель HTTPS, створити напрямок повідомлень пісочниці, що вказує на публічну URL, після чого запустити однопрохідний або життєвий цикл імітації проти цього призначення. Paddle надсилає реалістичний запит з Paddle-Signature головоломка, так що і той самий шлях перевірки сировини може працювати локально і в виробництві.
Чому симулятор Paddle більше, ніж зразок корисного навантаження
Скопіювати JSON тестує вашу звітність перемикача. Симулятор Paddle тестує мережеве призначення, заголовки провайдера, підписку секрету, статус реагування та події schema разом. Офіційна інформація Огляд тренажера webhook підтримує багаторазові події та сценарії. Одноразові події ціль одного типу події і можуть бути налаштовані після запуску. Сценаріо відправляється задану послідовність для життєвого циклу, таких як створення підписки або оновлення.
Конфігурація Scenario може з'являтися перевантаження з існуючими суб'єктами Paddle і змінювати потік. Кожен запуск виробляє імітаційно-розрядні записи подій, де можна перевірити навантаження, вихідний запит та відповідь кінцевої точки. Що робить тренажер корисною для відлагоджування державних переходів, не дивно, що маршрут онлайн.
Підключіть локальну кінцеву точку до пісочниці Paddle
- Почати заявку, наприклад,
http://localhost:3000й - Додати маршрут POST:
/api/webhooks/paddleй - Пробіг
npx portpreview 3000і скопіювати адресу HTTPS. - У пісочниці Paddle, створити пункт призначення повідомлень за допомогою
https://your-subdomain.portpreview.dev/api/webhooks/paddleй - Відкривайте та скопіюйте секрет кінцевої точки призначення
PADDLE_WEBHOOK_SECRET. Це не ваш ключ API. - Відкрийте інструменти розробника → Симулятори, виберіть єдиний захід або сценарій, виберіть пункт призначення, налаштуйте його і запустіть його.
- Порівняйте симуляторну відповідь Paddle з локальними журналами та персистентним отриманням webhook.
Використовуйте пісочниці та облікові дані по всій території. Змішуючи секрет в реальному часі з пісочним симулятором, запит гарантує відмову підпису навіть якщо обидва рядки виглядають чуйними.
Перевірити Paddle-Signature свінгери
Paddle призначає кожен вебхоок з секретом, що належить до пункту повідомлення. Заголовок містить компоненти, в тому числі одноразові мітки Unix ts та інші підписи, визначені h1. Paddle може додавати параметри підпису, тому, щоб парсер, а не припустимо, він містить одну лешу.
Підписано перезавантаження – це час, товста колонка, і доручений орган запиту. Paddle застосовує HMAC-SHA256 з секретом кінцевої точки. Своїм документація про перевірку підписів рекомендує офіційну SDK, де доступні та документи ручного алгоритму. Завжди дотримуйтесь допуску на часову допуску SDK або явної толерантності до вихідного коду, щоб обмежити атаки відтворення.
Подання офіційної SDK в Node
import express from 'express';
import { Environment, Paddle } from '@paddle/paddle-node-sdk';
const app = express();
const paddle = new Paddle(process.env.PADDLE_API_KEY, {
environment: Environment.sandbox,
});
app.post(
'/api/webhooks/paddle',
express.raw({ type: 'application/json' }),
async (req, res) => {
const signature = req.header('paddle-signature') ?? '';
const rawBody = req.body.toString('utf8');
try {
const event = await paddle.webhooks.unmarshal(
rawBody,
process.env.PADDLE_WEBHOOK_SECRET,
signature,
);
await acceptOnce(event.eventId, event);
return res.status(200).send('accepted');
} catch (error) {
return res.status(400).send('invalid webhook');
}
},
);
app.listen(3000);Навігація express.raw() перед будь-яким глобальним express.json() посередник для цього маршруту. У фетч-стилі, такі як Next.js App Router, використання await request.text() один раз і пропустіть, що точний рядок до SDK. Офіційна інформація вебхоок швидкийстарт продемонстрував цю вимогу до сирого тіла.
Яка ручна перевірка повинна робити
- Читати сире тіло без нормалізації JSON.
- Підтриманий кожний напівколонний компонент головки та збирання
h1значення. - Відхилити відсутню, необґрунтовану або незаймана
tsй - Поповнення
HMAC_SHA256(secret, ts + ':' + rawBody)й - Порівняти очікуваний дайджест з підписами кандидатів за допомогою timing-safe порівняння.
- Тільки після матчу, парс JSON і відправлення на
event_typeй
Прийняття будь-яких чинних підтримуваних підписів при таємному обертанні, коли може бути присутнім більше одного підпису. Не розбити заголовок і сліпо взяти другий елемент. Не ввійдіть секрет кінцевої точки або завершити перевантаження клієнтів при діагностуванні невідповідності.
Проектні імітації навколо варіантів
Створення підписки
Запустіть сценарій підписки та перевірте, що ваша база даних може отримувати пов’язані транзакції та підписки, не виходячи з одного порядку прибуття мережі. Магазин Paddle ідентифікаторів і оновлення записів idempotently. Заява повинна бути надана таким чином, якщо запит буде перебувати.
Поновлення та оплата
Вправа успішне оновлення, минуле та відновлення шляхів, доступні в налаштуваннях вашого сценарію. У зв'язку з політикою доступу до товарів: ваш пільговий період може навмисно зберігати активний доступ, а Paddle повідомляє про проблему збору.
Скасування та регулярні зміни
Відхилити підписку, що планується скасувати від одного, що досягла його ефективного скасування. Зареєструватися next_billed_atСтатус на сервери is_activeй
Оновлення вмісту
Симуляційний продукт, ціна, клієнт та оновлення підписки, що споживає кеш. Трейлер повинен ігнорувати невідомі типи заходів безпечно і визнати їх, якщо підпис дійсний; майбутні доповнення Paddle не повинні переходити в нескінченну петлю відмови.
Ідемпотенції та замовлення на кожен курс
Використовуйте стабільний ідентифікатор події Webhook як унікальний ключ у таблиці отримання. В одній угоді введіть квитанцію, застосуйте зміну стану, і закріпіть побічні ефекти. Якщо вставити конфлікти, повернути успіх без повторення роботи. Не слідувати лише ідентифікатором суб’єкта господарювання, оскільки багато законних оновлень можуть цільувати одну підписку.
Події можуть прибути з замовлення. Порівняйте час виникнення події або отримайте останні Paddle суб'єкта господарювання перед застосуванням руйнівного переходу. Зберігайте стан провайдера і своєчасність, і відхиляйте старі оновлення, які перезаписати новий. Симуляційні сценарії ідеально підходять для тестування цих припущення, оскільки вони виробляють з'єднані послідовності, а не ізольовані світильники.
Виправлення несправностей симулятора-до-локальної
Відправлення місць 404 або 405
Перевірте, що публічна URL-адреса включає в себе повний маршрут і що маршрут експортується POST. PXTERM00030XPP не є дійсним випробуванням POST-only webhook. Зареєструватися curl -X POST проти публічної URL для визначення маршрутизації тунелю з конфігурації Paddle.
Вихідні місця 400
Опитування Paddle-Signature прибув і підтвердити секрет кінцевої точки належить до обраного пункту повідомлення. Забезпечити не парсер, запит logger, або середнє програмне забезпечення, споживане або переформатовано тіло. Симулятор відправляє в'язані підписи, як задокументовані в Paddle кермай
Призначення повертається 500 або часу з
Швидко і швидко перемістити електронну пошту, надання та вихідні API дзвінки в чергу. Повернення 2xx після міцного прийняття. Покидання на однофазному типі події є загальною причиною непотрібних збоїв; використовувати відділення за замовчуванням, який записує і визнає його.
Сценарій використовує несподівані дані
Переглядайте, чи використовується імітаційне моделювання автоматично створених значень або популятор з реальними пісочницями. Перевірте налаштування параметрів сценаріїв та перезаряджання події, а не припустимо, що це дзеркалує попередній хід.
Контроль безпеки перед виробництвом
- Зберігайте ключі API та секрети призначення повідомлень окремо та серверно-тільки.
- Перевірити сире тіло, підпис заголовка і часовий запас перед обробкою.
- Використовуйте timing-safe порівняння або офіційний виверизатор SDK.
- Визначні ідентифікатори подій та обробка застарілих оновлень.
- Застосувати межі тіла, POST-тільки маршрутизація, перевиправлені залоги і контроль швидкості.
- Використовуйте різні пісочниці та живі напрямки, потім повторіть імітації та реальні витрати пісочниці перед перемиканням URL-адреси виробництва.
Симулятор доводить вашу інтеграцію під контролем послідовностей життєвого циклу; реальний пісочниця, додатково доводить зворотні зв'язки. Використовуйте обидва, потім ознайомтеся з загальним гід по підпису Webhook і Керівництво по роботі з клієнтами перед запуском.