v(i)b(e)c(o)d(e)4u.com
Назад на форум vbcd4u.com
🔥 Нейросети2026-11-17T10:06:00.000Z▲ 0 upvotes

Next.js App Router の Stripe Webhook: 署名、生の本体、冪等性

@murdasoftРедакция vbcd4u · MurdaSoft
Открыть все обсуждения →

Почему подпись проверяют до всего остального

URL вебхука не секрет: он может оказаться в логах, в коде, в истории браузера. Если обработчик верит любому POST-запросу с JSON вида checkout.session.completed, кто угодно может «оплатить» заказ, отправив его сам. Stripe подписывает каждое событие секретом конкретного эндпоинта (whsec_...) и передаёт подпись в заголовке Stripe-Signature. Проверка подписи — первая строка обработчика, до разбора JSON и любой бизнес-логики.

Обработчик в App Router

// app/api/stripe/webhook/route.ts
import Stripe from "stripe";
import { NextResponse } from "next/server";
import { db } from "@/lib/db";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
const endpointSecret = process.env.STRIPE_WEBHOOK_SECRET!;

export async function POST(req: Request) {
  const signature = req.headers.get("stripe-signature");
  if (!signature) return new NextResponse("missing signature", { status: 400 });

  const payload = await req.text(); // сырое тело, байт в байт

  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(payload, signature, endpointSecret);
  } catch {
    return new NextResponse("bad signature", { status: 400 });
  }

  const fresh = await db.query(
    "INSERT INTO stripe_events (id, type) VALUES ($1, $2) ON CONFLICT (id) DO NOTHING",
    [event.id, event.type]
  );
  if (fresh.rowCount === 0) return NextResponse.json({ received: true, duplicate: true });

  try {
    await handleEvent(event);
  } catch (err) {
    await db.query("DELETE FROM stripe_events WHERE id = $1", [event.id]);
    throw err; // 500 — Stripe повторит доставку
  }
  return NextResponse.json({ received: true });
}

Сырое тело

constructEvent считает HMAC от тела ровно в том виде, в каком его отправил Stripe. Если сначала вызвать req.json(), а потом JSON.stringify, порядок ключей, пробелы и экранирование будут другими, и подпись не совпадёт. В App Router отдельной настройки не требуется: req.text() возвращает тело без изменений. Конфиг bodyParser: false нужен только в старом Pages Router.

Обработчик должен работать в рантайме Node.js (по умолчанию так и есть). Если нужен Edge, используйте асинхронный вариант с Web Crypto:

const provider = Stripe.createSubtleCryptoProvider();
event = await stripe.webhooks.constructEventAsync(payload, signature, endpointSecret, undefined, provider);

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

Идемпотентность по event.id

Stripe гарантирует доставку «хотя бы один раз». Одно событие может прийти дважды: при сетевом сбое, при таймауте вашего ответа, при ручной повторной отправке из Dashboard. В live-режиме Stripe повторяет неудачные доставки в течение нескольких дней.

CREATE TABLE stripe_events (
  id          text PRIMARY KEY,         -- evt_...
  type        text NOT NULL,
  received_at timestamptz NOT NULL DEFAULT now()
);

Вставка с ON CONFLICT DO NOTHING атомарно отвечает на вопрос «видели ли мы это событие». Если обработка упала, запись удаляется, и повторная доставка обработается заново. Надёжнее — выполнять вставку события и изменения заказа в одной транзакции: тогда частично применённого состояния не бывает.

Обработка: не доверять порядку и снимку

async function handleEvent(event: Stripe.Event) {
  switch (event.type) {
    case "checkout.session.completed": {
      const session = event.data.object as Stripe.Checkout.Session;
      if (session.payment_status !== "paid") return; // асинхронные методы оплаты
      await markOrderPaid(session.client_reference_id!, session.id);
      return;
    }
    case "customer.subscription.updated":
    case "customer.subscription.deleted": {
      const sub = event.data.object as Stripe.Subscription;
      const current = await stripe.subscriptions.retrieve(sub.id);
      await syncSubscription(current);
      return;
    }
    default:
      return; // неизвестные типы — 200, иначе Stripe будет повторять
  }
}

События не обязаны приходить в порядке возникновения: subscription.updated может прийти раньше subscription.created. Объект в событии — снимок на момент события, а не текущее состояние. Для подписок надёжнее перечитать объект через API и синхронизировать актуальное состояние, чем применять снимки по очереди.

client_reference_id вы передаёте при создании Checkout Session — по нему находите свой заказ. Сумму сверяйте с суммой из вашей базы, а не берите из события на веру.

Быстрый ответ

Stripe ждёт ответа 2xx за ограниченное время. Отправка писем, генерация PDF и вызовы сторонних API внутри обработчика удлиняют ответ и увеличивают шанс повторной доставки. Тяжёлую работу ставьте в очередь или таблицу задач, а в обработчике только фиксируйте факт.

Локальная проверка

stripe listen --forward-to localhost:3000/api/stripe/webhook
# выведет whsec_... — это секрет для локального запуска, он отличается от секрета в Dashboard
stripe trigger checkout.session.completed

Диагностика

  • «No signatures found matching the expected signature». Тело изменено до проверки, или секрет не от этого эндпоинта. У тестового и live-режима, у CLI и у каждого эндпоинта в Dashboard свои секреты.
  • Подпись не совпадает только в продакшене. Прокси или платформа перед приложением изменяет тело (сжатие, перекодировка). Проверьте, что запрос доходит без преобразований.
  • Дубли заказов. Нет уникального ограничения на event.id или на идентификатор заказа, обработка не идемпотентна.
  • Поля в событии отличаются от документации. Формат событий определяется версией API, выбранной для эндпоинта в Dashboard, а не версией SDK в коде.

Когда достаточно меньшего

Если оплат единицы и заказы подтверждаются вручную, хватит проверки подписи и уникального ключа на заказ. Таблица событий и очередь окупаются, когда после оплаты автоматически выдаётся доступ, отправляются письма или меняются подписки.

Обсуждение (0)

Ещё на vbcd4u.com