> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# Идемпотентные вебхуки Stripe и Lemon Squeezy в Next.js

Как проверять подписи необработанных вебхуков, дедуплицировать повторные доставки на границе базы данных и не позволять пересекающимся подпискам отзывать платный доступ.

_Опубликовано 2026-10-18._
_Обновлено 2026-10-18._

> **Как идемпотентно обрабатывать вебхуки Stripe и Lemon Squeezy в Next.js?**
> Зависит от ваших платёжных провайдеров, но базовая архитектура одинакова: проверяйте подпись необработанного payload до разбора JSON, нормализуйте события провайдеров в общий внутренний контракт и обеспечивайте идемпотентность на границе базы данных по ID события или заказа провайдера. Никогда не выдавайте права доступа из клиентского редиректа после оплаты, пусть проверенный вебхук транзакционно обновит состояние подписки и права доступа ровно один раз. supastack уже соединяет этот конвейер для Stripe, Lemon Squeezy и мобильного RevenueCat, хотя приложения с одним тарифом могут начать с более простого обработчика.

## Проверяйте необработанный payload до разбора JSON

Каждый платёжный провайдер подписывает точную последовательность байтов, отправляемую по сети. Если обработчик маршрута вызывает `await request.json()` и заново сериализует объект перед проверкой подписи, различия в порядке ключей или пробелах сделают легитимные вебхуки недействительными, или подтолкнут разработчиков отключить проверку на стейджинге.

Прочитайте необработанное тело один раз через `await request.text()` в обработчике `POST` Next.js App Router, проверьте криптографическую подпись с помощью серверного секрета вебхука и отклоняйте любые несовпадения с кодом HTTP 400 до выполнения первого запроса к базе. [Руководство по модулю биллинга](https://supastack.dev/ru/docs/modules/billing.md) показывает, как supastack изолирует проверку подписей за единой точкой входа BFF.

- Читайте необработанное тело запроса через `request.text()`, никогда не сериализуйте разобранный JSON повторно.
- Храните `STRIPE_WEBHOOK_SECRET` и секреты подписи Lemon Squeezy исключительно в серверной конфигурации.
- Используйте сравнение за постоянное время (`crypto.timingSafeEqual`) при ручной проверке подписей HMAC.

```
export async function POST(request: Request) {
  const rawBody = await request.text();
  const signature = request.headers.get("stripe-signature");
  if (!signature) return new Response("Missing signature", { status: 400 });

  const event = stripe.webhooks.constructEvent(
    rawBody,
    signature,
    env.STRIPE_WEBHOOK_SECRET,
  );
  await handleNormalizedBillingEvent(event);
  return Response.json({ received: true });
}
```


## Дедуплицируйте на границе базы данных, а не в памяти

Stripe и Lemon Squeezy повторяют отправку вебхуков при перезапуске деплоя, таймауте бессерверной функции или потере ответа в сети. Локальные для процесса коллекции или короткоживущие ключи кэша теряются между инстансами и не помешают двум одновременным повторам выдать дубликат лицензии или отправить два письма с квитанцией.

Записывайте ID события провайдера или статус оплаты заказа в той же транзакции Postgres, которая изменяет доступ по подписке. Атомарный `INSERT ... ON CONFLICT DO NOTHING` или условное обновление по `status != 'paid'` превращает параллельный повтор в безопасную пустую операцию. При проектировании тарифов, которые активируют эти вебхуки, [генератор страницы тарифов SaaS](https://supastack.dev/ru/tools/saas-pricing-generator) помогает заранее смоделировать уровни и правила расчёта мест.

```
const settled = await db.transaction(async (tx) => {
  const [inserted] = await tx
    .insert(billingWebhookEvents)
    .values({ providerEventId: event.id, provider: "stripe" })
    .onConflictDoNothing({ target: billingWebhookEvents.providerEventId })
    .returning({ id: billingWebhookEvents.id });

  if (!inserted) return false; // Already processed
  await applyWorkspaceEntitlement(tx, event);
  return true;
});
```

- [SaaS Pricing Page Generator (Free Tool)](https://supastack.dev/tools/saas-pricing-generator)


## Обрабатывайте события вне очереди и пересекающиеся подписки

Вебхуки не обязаны приходить в том порядке, в котором нажимал пользователь. `customer.subscription.updated` может прийти раньше `checkout.session.completed`, а клиент, случайно открывший две вкладки оплаты, может на короткое время получить две подписки в одном воркспейсе.

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

- Храните состояние подписки по ключу `providerSubscriptionId`, а не только по `workspaceId`.
- Сохраняйте платный доступ воркспейса активным, пока хотя бы одна подписка находится в статусе `active` или `trialing`.
- Проверяйте совпадение оплаченной суммы и валюты с ожидаемым SKU перед выполнением разовых заказов.


## Частые вопросы о платёжных вебхуках в SaaS

Эти вопросы возникают всякий раз, когда команда переводит биллинг из песочницы на реальный продакшен-трафик.

- Можно ли открывать платные функции сразу при редиректе на страницу успешной оплаты?, Нет. Ссылку редиректа можно сохранить в закладки, переслать или открыть до завершения асинхронного платежа. Используйте страницу успеха для опроса состояния сервера, пока проверенный вебхук выдаёт доступ.
- Какой код ответа должен возвращать дублирующийся вебхук?, Возвращайте `200 OK`, как только база данных подтвердит, что событие уже обработано. Ответ `4xx` или `5xx` заставит провайдера продолжать повторные попытки.
- Как локально тестировать повторную доставку вебхуков?, Напишите детерминированные модульные тесты, которые дважды отправляют один и тот же подписанный payload, и проверьте, что создаётся только одна лицензия, одно право доступа или одно транзакционное письмо.
- Как мобильные встроенные покупки вписываются в ту же модель?, Направляйте серверные уведомления RevenueCat в ту же идемпотентную таблицу прав доступа, чтобы веб- и мобильные покупки никогда не перезаписывали друг друга, список проверок перед релизом есть в [чек-листе запуска](https://supastack.dev/ru/blog/saas-launch-checklist.md).
