Webhooks Stripe dans Next.js App Router : signature, corps brut et idempotence
Почему подпись проверяют до всего остального
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 в коде.
Когда достаточно меньшего
Если оплат единицы и заказы подтверждаются вручную, хватит проверки подписи и уникального ключа на заказ. Таблица событий и очередь окупаются, когда после оплаты автоматически выдаётся доступ, отправляются письма или меняются подписки.