Next.js App Router-dagi chiziqli veb-kanuklar: imzo, xom ashyo va identifikatorlik
Nima uchun hamma narsadan oldin imzo tekshiriladi?
Webhook URL manzili sir emas: u jurnallarda, kodda, brauzer tarixida tugashi mumkin. Agar ishlov beruvchi checkout.session.completed kabi JSON bilan har qanday POST soʻroviga ishonsa, har kim buyurtmani oʻzi yuborish orqali “toʻlashi” mumkin. Stripe har bir hodisani oxirgi nuqtaga xos sir (whsec_...) bilan imzolaydi va imzoni Stripe-Signature sarlavhasiga uzatadi. Imzoni tekshirish JSON va har qanday biznes mantiqini tahlil qilishdan oldin ishlov beruvchining birinchi qatoridir.
Ilova Routeridagi ishlov beruvchi
// 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 });
}Xom tana
constructEvent tanadan HMAC ni Stripe tomonidan yuborilganidek hisoblab chiqadi. Agar siz avval req.json() ga, keyin esa JSON.stringify ga qo'ng'iroq qilsangiz, kalitlar, bo'shliqlar va qochish tartibi boshqacha bo'ladi va imzo mos kelmaydi. App Router-da alohida konfiguratsiya talab qilinmaydi: req.text() tanani o'zgarishsiz qaytaradi. bodyParser: false konfiguratsiyasi faqat eski Pages Routerda kerak.
Ishlovchi Node.js ish vaqtida ishlashi kerak (u sukut bo'yicha ishlaydi). Agar sizga Edge kerak bo'lsa, Web Crypto bilan asinxron variantdan foydalaning:
const provider = Stripe.createSubtleCryptoProvider(); event = await stripe.webhooks.constructEventAsync(payload, signature, endpointSecret, undefined, provider);
Tekshiruv, shuningdek, to'xtatilgan so'rovni qayta yuborishdan himoya qiluvchi juda eski vaqt tamg'asi bilan hodisalarni rad etadi (standart bardoshlik 5 daqiqa).
event.id bo'yicha idempotency
Stripe "kamida bir marta" yetkazib berishni kafolatlaydi. Bitta hodisa ikki marta sodir bo'lishi mumkin: tarmoq ishlamay qolganda, javob vaqti tugashi paytida yoki asboblar panelidan qo'lda qayta yuborilganda. Jonli rejimda Stripe bir necha kun davomida muvaffaqiyatsiz yetkazib berishni takrorlaydi.
CREATE TABLE stripe_events ( id text PRIMARY KEY, -- evt_... type text NOT NULL, received_at timestamptz NOT NULL DEFAULT now() );
ON CONFLICT DO NOTHING qoʻshimchasi “biz bu hodisani koʻrdikmi?” degan savolga atomik tarzda javob beradi. Agar qayta ishlash muvaffaqiyatsiz tugasa, yozuv o'chiriladi va qayta yetkazib berish qayta ishlanadi. Bitta tranzaksiyada hodisa va buyurtma o'zgarishini kiritish ishonchliroq: u holda qisman qo'llaniladigan holat yo'q.
Qayta ishlash: buyurtma va rasmga ishonmang
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 будет повторять
}
}Voqealarning sodir bo'lish tartibi bo'yicha kelishi shart emas: subscription.updated subscription.created dan oldin kelishi mumkin. Hodisadagi ob'ekt joriy holat emas, balki voqea vaqtidagi oniy rasmdir. Obunalar uchun ob'ektni API orqali qayta o'qish va joriy holatni sinxronlashtirish oniy tasvirlarni birma-bir ishlatishdan ko'ra ishonchliroqdir.
Hisob-kitob seansini yaratishda siz client_reference_id ni topshirasiz - buyurtmangizni topish uchun undan foydalaning. Miqdorni ma'lumotlar bazasidagi miqdor bilan tekshiring va uni imon bo'yicha voqeadan olmang.
Tez javob
Stripe 2xx javobini cheklangan vaqt kutadi. Elektron pochta xabarlarini yuborish, PDF-fayllarni yaratish va ishlov beruvchi ichida uchinchi tomon API-lariga qo'ng'iroq qilish javobni uzaytiradi va qayta yetkazib berish imkoniyatini oshiradi. Qiyin ishni navbatga yoki topshiriqlar jadvaliga qo'ying va faqat ishlov beruvchiga faktni yozib qo'ying.
Mahalliy tekshirish
stripe listen --forward-to localhost:3000/api/stripe/webhook # выведет whsec_... — это секрет для локального запуска, он отличается от секрета в Dashboard stripe trigger checkout.session.completed
Diagnostika
- “Kutilayotgan imzoga mos keladigan imzo topilmadi.” Tasdiqlashdan oldin matn o‘zgartirilgan yoki sir bu oxirgi nuqtadan emas. Sinov va jonli rejimlar, CLI va asboblar panelidagi har bir so'nggi nuqta o'z sirlariga ega.
- Imzo faqat ishlab chiqarishda mos kelmaydi. Proksi-server yoki platforma ilovadan oldin korpusni o'zgartiradi (siqish, qayta kodlash). So'rov o'zgarishlarsiz kelishini tekshiring.
- Buyurtmalarni takrorlash.
event.idyoki buyurtma identifikatorida yagona cheklov yo'q, qayta ishlash idempotent emas. - Tadbirdagi maydonlar hujjatlardagidan farq qiladi. Voqea formati koddagi SDK versiyasi emas, balki asboblar panelidagi so‘nggi nuqta uchun tanlangan API versiyasi bilan belgilanadi.
Qachon kamroq bo'lsa
Agar to'lovlar birliklarda amalga oshirilsa va buyurtmalar qo'lda tasdiqlansa, imzo va buyurtma uchun yagona kalitni tekshirish kifoya. To'lovdan so'ng avtomatik ravishda kirish huquqi berilganda, xatlar yuborilganda yoki obunalar o'zgartirilganda tadbirlar jadvali va navbat o'z-o'zidan to'lanadi.