Локальне тестування вебхуків Polar через Polar CLI

Щоб протестувати веб-хуки Polar локально, запустіть обробник веб-хуків, установіть і автентифікуйте Polar CLI, а потім використовуйте polar listen http://localhost:3000/api/webhooks/polar щоб передавати підписані події безпосередньо на вашу машину. Скопіюйте тимчасовий секрет, надрукований слухачем POLAR_WEBHOOK_SECRET, перевірити необроблене тіло перед його обробкою та ініціювати подію перевірки ізольованого програмного середовища, замовлення, відшкодування або підписки.

Чому Polar CLI є найпростішим локальним робочим процесом

Звичайна робоча кінцева точка вебхуку має бути загальнодоступною через HTTPS. Polar пропонує спеціально створений локальний слухач, тож вам не потрібно створювати постійну кінцеву точку або постійно вставляти тимчасові URL-адреси зворотного виклику на інформаційну панель. CLI підключається до вашої організації, відображає секрет підпису сеансу, отримує події та пересилає їх на локальну URL-адресу, яку ви надаєте.

Полярний офіційний локальна документація webhook використовує polar listen http://localhost:3000/. Наведіть його на повний шлях, коли ваша програма обробляє веб-хуки нижче маршруту, наприклад /api/webhooks/polar. Це вловлює помилки шляху до виробництва та зберігає той самий обробник програми, який ви збираєтеся розгорнути.

Встановіть CLI і почніть слухати

1. Запустіть свою програму та переконайтеся, що її маршрут POST доступний локально.
2. Встановіть Polar CLI за допомогою команди з офіційної документації.
3. бігти polar login і авторизуйте правильний обліковий запис.
4. Почніть polar listen http://localhost:3000/api/webhooks/polar.
5. Виберіть організацію, якій належать ваші продукти ізольованого програмного середовища.
6. Скопіюйте показаний секрет сеансу в POLAR_WEBHOOK_SECRET і перезапустіть програму, якщо її середовище завантажується лише під час запуску.
7. Запустіть дію ізольованого програмного середовища та порівняйте статус доставки CLI з локальними журналами.

Секрет слухача є частиною локального сеансу. Не припускайте, що він дорівнює секрету кінцевої точки інформаційної панелі та не використовуйте повторно значення виробництва. Якщо ви повторно підключитесь і отримаєте інший секрет, оновіть локальне середовище перед повторним тестуванням.

Створіть обробник маршрутизатора програми Next.js

Polar дотримується специфікації Standard Webhooks. Доставка включає в себе webhook-id, webhook-timestamp, і webhook-signature. Перевірка повинна використовувати точне необроблене тіло запиту; виклик request.json() спочатку та повторна серіалізація об’єкта може змінити підписані байти.

// app/api/webhooks/polar/route.ts
import { Webhook } from 'standardwebhooks';

export const runtime = 'nodejs';

export async function POST(request: Request) {
  const rawBody = await request.text();
  const secret = process.env.POLAR_WEBHOOK_SECRET;
  if (!secret) {
    return new Response('Webhook secret is not configured', { status: 500 });
  }

  const headers = {
    'webhook-id': request.headers.get('webhook-id') ?? '',
    'webhook-timestamp': request.headers.get('webhook-timestamp') ?? '',
    'webhook-signature': request.headers.get('webhook-signature') ?? '',
  };

  try {
    const encodedSecret = Buffer.from(secret.trim(), 'utf8').toString('base64');
    const payload = new Webhook(encodedSecret).verify(rawBody, headers);
    await acceptPolarEvent(headers['webhook-id'], payload);
    return Response.json({ received: true });
  } catch {
    return new Response('Invalid signature', { status: 403 });
  }
}

Полярний документація на поставку викликає загальну пастку спеціальної перевірки: стандартні бібліотеки Webhooks очікують секрету, закодованого Base64, тоді як Polar надає звичайний секретний рядок. Помічники Polar SDK обробляють це перетворення автоматично. При використанні standardwebhooks напряму, закодуйте Base64 повний секрет Polar, як показано вище.

Віддавайте перевагу офіційному адаптеру фреймворку, якщо він доступний

Polar публікує адаптери, які поєднують перевірку підпису з обробниками введеного корисного навантаження. Чиновник Документація на експрес-адаптер надає детальні зворотні виклики для подій оформлення замовлення, повернення коштів, переваг і підписки. Адаптер зменшує ймовірність неправильного впровадження аналізу заголовка або секретного кодування.

import express from 'express';
import { Webhooks } from '@polar-sh/express';

const app = express();
app.use(express.json());
app.post('/webhooks/polar', Webhooks({
  webhookSecret: process.env.POLAR_WEBHOOK_SECRET,
  onOrderPaid: async (event) => {
    await queueOrderPaid(event.data);
  },
  onSubscriptionActive: async (event) => {
    await queueSubscriptionActive(event.data);
  },
}));
app.listen(3000);

Дотримуйтеся задокументованого порядку проміжного програмного забезпечення адаптера для версії, яку ви встановлюєте. Якщо замість цього ви використовуєте загальний верифікатор, явно збережіть необроблене тіло. Не змішуйте адаптер, який читає потік, із проміжним програмним забезпеченням, яке споживає його першим.

Які полярні події ви повинні перевірити?

Події на касі

Події Checkout допомагають відстежувати сеанс до того, як він стане оплаченим замовленням. Перевірте успішне завершення та залишені чи оновлені стани без надання доступу лише тому, що було створено перевірку. Оплачене замовлення або активна підписка мають залишатися авторитетним сигналом надання прав.

Замовлення оплачено та повернуто кошти

Для події, оплаченої замовленням, зіставте клієнта та продукт Polar зі своїм внутрішнім обліковим записом, а потім надайте придбану перевагу рівно один раз. Події відшкодування мають скасовувати лише відповідне право відповідно до вашої політики відшкодування. Зберігайте ідентифікатори постачальників, щоб служба підтримки могла узгодити подію з Polar.

Події життєвого циклу підписки

Створення тестів, активація, оновлення, скасування, відкликання та будь-яка прострочена поведінка, яку підтримує ваш продукт. Запит на скасування може не означати негайного припинення доступу. Зберігайте статус і дати набрання чинності замість скорочення життєвого циклу до одного is_active прапор.

Допомоги

Якщо ваша інтеграція використовує переваги Polar, протестуйте створення, оновлення та відкликання гранту незалежно від подій виставлення рахунків. Зробіть так, щоб обробники наближалися до потрібного стану, щоб двічі отримати той самий грант, що не створювало дублікатів ресурсів.

Зробіть кожну подію ідемпотентною

Доставка через мережу не є одноразовою транзакцією. Обробник може закріпити свою роботу з базою даних і втратити відповідь, змусивши відправника повторити спробу. використання webhook-id як унікальний ключ доставки та вимагайте його в тій самій транзакції, яка оновлює стан вашої програми.

await db.transaction(async (tx) => {
  const firstDelivery = await tx.webhookReceipts.insertIfAbsent({
    provider: 'polar',
    deliveryId: webhookId,
  });
  if (!firstDelivery) return;

  await applyPolarEvent(tx, payload);
  await tx.outbox.enqueue('polar-event-accepted', { webhookId });
});

Повернути відповідь 2xx для дубліката, який уже було завершено. Не видаляйте дублікати лише за ідентифікатором клієнта або підписки, оскільки багато законних подій спрямовані на той самий ресурс. The повторна спроба вебхука та посібник із ідемпотентності більш детально охоплює шаблони папок «Вхідні» та «Вихідні».

Робіть роботу підтвердження короткою

Перевірте запит, збережіть його або поставте в чергу довготривале завдання та поверніть успіх. Електронна пошта, генерація ліцензій, доступ до сховища, аналітика та виклики API сторонніх розробників мають працювати асинхронно. Швидке підтвердження зменшує повторні спроби, а тривалий запис запобігає зникненню подій, якщо процес завершується після повернення.

Невідомі типи подій слід записувати та підтверджувати після перевірки дійсного підпису. Polar може з часом додавати типи подій; використання кожного незнайомого значення перетворює нешкідливе додавання схеми в повторювані помилки доставки.

Усунення неполадок локального хосту webhook Polar

CLI підключається, але маршрут повертає 404

Пройдіть повний місцевий маршрут до polar listen, не тільки порт. У Next.js App Router переконайтеся, що файл має назву route.ts та експорт POST. Браузер GET, який повертає 404, не доводить, що маршрут POST відсутній, тому перевірте за допомогою curl -X POST.

Кожен запит повертає 403

Підтвердьте, що програма завантажила секрет, надрукований поточним сеансом CLI. Збережіть необроблене тіло та всі три заголовки Standard Webhooks. Якщо ви використовуєте загальну бібліотеку, Base64-кодує секрет Polar рівно один раз; якщо ви використовуєте помічник Polar SDK, передайте оригінальний секрет і дозвольте SDK обробити кодування.

Жодна подія не з’являється після оформлення замовлення

Переконайтеся, що CLI підключено до тієї самої організації та середовища, де відбулася дія. Тримайте термінал слухача відкритим, використовуйте ресурси пісочниці та переконайтеся, що ваша дія дійсно досягає стану події, на який ви підписалися.

Події обробляються двічі

Додайте унікальне обмеження для webhook-id і повернути успіх для дублікатів. Перевірте, чи виникає виняток після оновлення стану, але до відповіді. Перемістіть повільні побічні ефекти в вихідну скриньку.

Старий захоплений запит не пройшов перевірку

Стандартна перевірка Webhooks включає мітку часу, щоб обмежити атаки відтворення. Старий запис не повинен пройти звичайне вікно перевірки. Для тестів бізнес-логіки один раз перевірте свіжу доставку та збережіть дезінфікований пристрій корисного навантаження за межею автентифікації.

Контрольний список безпеки перед виробництвом

• Використовуйте окремі локальні, пісочниці та робочі секрети кінцевих точок.
• Перед обробкою перевірте необроблений текст, мітку часу, ідентифікатор доставки та підпис.
• Зберігайте маркери API та секрети вебхука у змінних середовища лише для сервера.
• Дедуплікати за webhook-id перевірити ідентифікатори продукту, організації та клієнта.
• Видалення електронної пошти клієнтів, платіжних даних, метаданих і повного корисного навантаження зі спільних журналів.
• Застосовуйте обмеження розміру запиту та відстежуйте повторювані недійсні підписи.
• Замініть локальний приймач на стабільну кінцеву точку HTTPS і протестуйте новий потік ізольованого програмного середовища перед увімкненням живих продуктів.

Інтерфейс командного рядка Polar усуває цикл розгортання, але він не повинен усувати засоби керування виробництвом. Увімкніть перевірку підпису, ідемпотентність, фільтрацію подій і тривалу обробку локально, щоб код, який ви тестуєте, був кодом, який ви надсилаєте. Щоб отримати відомості про перевірку незалежної від фреймворку, прочитайте інструкція з перевірки підпису webhook і заг локальний робочий процес налагодження.