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

Вебхукі Stripe в Next.js App Router: підпис, сире тіло та ідемпотентність

@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 у коді.

Коли досить меншого

Якщо оплати одиниці та замовлення підтверджуються вручну, вистачить перевірки підпису та унікального ключа на замовлення. Таблиця подій та черга окупаються, коли після оплати автоматично видається доступ, надсилаються листи або змінюються підписки.

Нужна реализация под ваш проект или аудит архитектуры?

Разрабатываем сайты на Next.js, Telegram-ботов, интеграции с CRM и ИИ-агентов под ключ.

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

Ещё на vbcd4u.com