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

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

Почему Polar CLI — самый простой локальный рабочий процесс

Обычная конечная точка рабочего веб-перехватчика должна быть общедоступной через HTTPS. Polar предлагает специально созданный локальный прослушиватель, поэтому вам не придется создавать постоянную конечную точку или повторно вставлять временные URL-адреса обратного вызова на панель мониторинга. Интерфейс командной строки подключается к вашей организации, отображает секрет подписи сеанса, получает события и перенаправляет их на предоставленный вами локальный URL-адрес.

Официальный представитель Polar документация по локальному вебхуку использует 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 следует спецификации стандартных веб-перехватчиков. В комплект поставки входит 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);

Следуйте документированному порядку промежуточного программного обеспечения адаптера для устанавливаемой версии. Если вместо этого вы используете универсальный верификатор, явно сохраните необработанное тело. Не смешивайте адаптер, который читает поток, с промежуточным программным обеспечением, которое сначала его потребляет.

Какие полярные события стоит протестировать?

События оформления заказа

События оформления заказа помогают отслеживать сеанс до того, как он станет оплаченным заказом. Протестируйте успешное завершение, а также состояния отказа или обновления, не предоставляя доступ только потому, что была создана проверка. Оплаченный заказ или активная подписка должны оставаться авторитетным сигналом о предоставлении прав.

Заказ оплачен и возвращен

Для мероприятия с оплатой заказа сопоставьте клиента и продукт 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 для уже выполненного дубликата. Не выполняйте дедупликацию только по идентификатору клиента или подписки, поскольку многие законные события нацелены на один и тот же ресурс. Руководство по повторной попытке веб-перехватчика и идемпотентности более подробно рассматриваются шаблоны входящих и исходящих сообщений.

Работа по подтверждению должна быть короткой

Проверьте запрос, сохраните его или поставьте в очередь долговременное задание и верните успех. Электронная почта, создание лицензий, доступ к хранилищу, аналитика и вызовы сторонних API должны выполняться асинхронно. Быстрое подтверждение сокращает количество повторных попыток, а надежная запись предотвращает исчезновение событий, если процесс завершается после возврата.

Неизвестные типы событий должны регистрироваться и подтверждаться после проверки действительной подписи. Polar может со временем добавлять типы событий; добавление каждого незнакомого значения превращает безобидное добавление схемы в повторяющиеся сбои доставки.

Устранение неполадок локального хоста веб-перехватчика Polar

CLI подключается, но маршрут возвращает 404.

Пройдите полный местный маршрут до polar listen, не только порт. В маршрутизаторе приложений Next.js убедитесь, что файл назван route.ts и экспорт POST. GET браузера, возвращающий 404, не доказывает отсутствие маршрута POST, поэтому проверьте с помощью curl -X POST.

Каждый запрос возвращает 403

Убедитесь, что приложение загрузило секрет, напечатанный в текущем сеансе CLI. Сохраните необработанное тело и все три заголовка стандартных веб-перехватчиков. Если вы используете универсальную библиотеку, Base64 закодирует секрет Polar ровно один раз; если вы используете помощник Polar SDK, передайте исходный секретный код и позвольте SDK обрабатывать кодировку.

После оформления заказа ни одно событие не появляется

Убедитесь, что CLI подключен к той же организации и среде, где произошло действие. Держите терминал прослушивателя открытым, используйте ресурсы песочницы и убедитесь, что ваше действие действительно достигает состояния события, на которое вы подписались.

События обрабатываются дважды

Добавьте уникальное ограничение для webhook-id и вернуть успех для дубликатов. Проверьте, возникает ли исключение после обновления состояния, но до ответа. Перенесите медленные побочные эффекты в рабочий процесс с поддержкой исходящих сообщений.

Старый перехваченный запрос не проходит проверку

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

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

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

Polar CLI устраняет цикл развертывания, но не должен удалять элементы управления производством. Включите проверку подписи, идемпотентность, фильтрацию событий и устойчивую обработку локально, чтобы тестируемый вами код был именно тем кодом, который вы отправляете. Подробности независимой от платформы проверки см. руководство по проверке подписи вебхука и генерал локальный рабочий процесс отладки.