MENU

問い合わせ


    【Next.jsで作るオンライン予約サービス 第7回】Webhookで予約を確定する(署名の検証・二重処理の防止・仮予約の期限切れ)

    (2026年10月29日 追記:記事どおりに再現できるよう、必要なコードと手順を追加しました)

    オンライン予約サービスで「支払いが済んだのに予約が確定していない」「同じ支払いで二重に処理された」といったトラブルは、決済サービスからの通知(Webhook)の受け方で決まります。この回では、Stripe(ストライプ。クレジットカード決済などを提供する海外の決済サービス)から届く「支払いが終わりました」という通知を安全に受け取り、仮予約を確定させるところまでを作ります。

    「支払いが終わったはずなのに、予約が確定しない。逆に、同じ通知が2回届いて二重に処理されたりしないか心配…」

    先に結論です。予約を確定してよいのは、Stripe から届いた署名つきの通知を受けたときだけです。そのうえで、「署名を確かめる」「同じ通知は一度しか処理しない」「金額が合うか確かめる」「期限切れとの競合を決めておく」の4点を押さえれば、小さな予約サービスでも支払いと予約のずれを防げます。

    前回の第6回(Stripeで支払いを受ける)では、予約を「支払い待ち」の仮予約として保存し、Stripe の決済ページ(Checkout)へ利用者を移すところまで作りました。今回はその続きで、支払い結果を受け取って予約を確定します。

    目次

    この回で作るもの:支払い完了の通知を受けて予約を確定する流れ

    Webhook(ウェブフック)とは、Stripe のサーバーから自社のサーバーへ、出来事を知らせるために送られる通知のことです。利用者のブラウザを経由しないので、画面を閉じられても、URL を書き換えられても影響を受けません。流れは次のとおりです。

    順番起きること担当
    1利用者が Stripe のページで支払うStripe
    2Stripe が自社の通知用 URL(/api/stripe/webhook)へ通知を送るStripe → 自社サーバー
    3通知の署名を確かめる。合わなければ拒否する自社サーバー
    4同じ通知を処理済みでないか確かめる自社サーバー+DB
    5金額などを予約と照らし合わせ、仮予約を確定にする自社サーバー+DB
    6成功の応答(2xx)を返す。失敗したら 500 を返し、Stripe に再送してもらう自社サーバー

    使ったバージョンは Next.js 16・Stripe の Node.js ライブラリ 23 です。この回で足すファイルの全文と、既存のファイルへの変更点は、各項目に載せています。

    📰 出典:Stripe ドキュメント「Receive Stripe events in your webhook endpoint」

    仕組みの説明:安全に通知を受ける4つの考え方

    署名:通知が本当に Stripe から来たかを確かめる

    通知を受ける URL は、誰でも外から呼べる状態になります。もし署名を確かめずに受け入れると、第三者が「支払い済み」という偽の通知を送って、お金を払わずに予約を確定できてしまいます。

    Stripe は通知ごとに、本文と時刻から計算した署名を stripe-signature というヘッダーに付けます。自社側は、Webhook用のシークレット(whsec_ で始まる合言葉)で同じ計算をし、一致するかを確かめます。公式のライブラリでは、署名の時刻が5分以上ずれている通知も既定で拒否されます(使い回しの防止)。

    署名の計算には、届いた本文の文字列そのままが必要です。JSON に直したあとの値では計算が合わなくなるため、後ほどのコードでも本文は文字列のまま読みます。

    二重処理の防止:同じ通知は何度でも届きうる

    Stripe は、自社のサーバーが 2xx 以外を返したり、応答が遅れたりすると、通知を再送します(本番環境では最大3日間、間隔を広げながら再送。テスト環境では数時間に3回)。また、まれに同じ通知が重ねて届くこともあります。通知の順番も保証されません。

    そこで、処理した通知の ID(evt_ で始まる Stripe のイベントID)を表に記録し、すでにあるものは何もしないようにします。

    📰 出典:Stripe ドキュメント「Handle duplicate events」(Webhooks のベストプラクティス)

    照合:通知の内容が予約と合うか確かめる

    署名が正しくても、通知の内容をそのまま信じるのは避けます。今回は次の3つを予約と照らし合わせ、1つでも合わなければ確定せずログに残します。

    • 通知に含まれる決済ページの ID が、予約に結びつけた ID と同じか(第6回で保存した値)
    • 支払われた金額が、予約時にサーバーが計算した金額と同じか
    • 支払い状態が「支払い済み(paid)」か(コンビニ払いのように、決済ページの完了後に入金が遅れる方法では、この時点で未払いのことがある)

    期限切れとの競合:支払いが期限より遅れて届いたら

    第6回で、仮予約の期限(35分)が切れると枠が解放されるようにしました。ところが、支払いの通知が期限より後に届くことがあります。この場合の扱いを決めておかないと、お金だけ受け取って予約がない、という最悪の状態になります。今回は次のルールにしました。

    状況扱い
    期限内に通知が届いた確定にする
    期限切れのあとに届いたが、枠はまだ空いている確定に戻す
    期限切れのあとに届き、枠を別の人が取っていた確定にせず、「支払い済み」の印だけ残して返金対象にする(返金は次回)

    最後の判断を人の目に頼らず、第4回で作った排他制約(同じ時間の予約を DB が拒否する仕組み)にそのまま任せるのがポイントです。確定に戻す更新が制約違反になれば、枠が埋まっているとわかります。

    実装

    1. 通知の記録用の表と、支払い日時の列を足す

    lib/schema.ts に、処理した通知の表と、予約の支払い日時の列を追加しました。マイグレーションは drizzle/0006_webhook.sql です。

    lib/schema.ts に次の変更を加えます(+ が追加、- が削除)

    --- a/lib/schema.ts
    +++ b/lib/schema.ts
    @@ -69,10 +69,18 @@ export const reservations = pgTable(
         totalYen: integer("total_yen"), // 予約時にサーバーが計算した金額(円)。支払いの金額はここから作る
         holdExpiresAt: timestamp("hold_expires_at", { withTimezone: true }), // 仮予約で枠を押さえておく期限
         stripeSessionId: text("stripe_session_id").unique(), // Stripe の決済ページ(Checkout Session)の ID
    +    paidAt: timestamp("paid_at", { withTimezone: true }), // 支払いを確認した日時(第7回)。確定の有無とは別に「お金が入った事実」を残す
         createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
       },
       // 「このスペースの、この日の予約」を速く探すための索引
       (t) => [index("reservations_space_starts_idx").on(t.spaceId, t.startsAt), index("reservations_user_idx").on(t.userId, t.startsAt)],
     );
     
    +// 処理した Stripe の通知(イベント)の表。同じ通知は何度でも届きうるため、イベント ID を主キーにして二重処理を防ぐ(第7回)
    +export const stripeEvents = pgTable("stripe_events", {
    +  id: text("id").primaryKey(), // Stripe のイベント ID(evt_...)
    +  type: text("type").notNull(),
    +  processedAt: timestamp("processed_at", { withTimezone: true }).notNull().defaultNow(),
    +});
    +
     export type Reservation = typeof reservations.$inferSelect;

    イベントIDを主キーにすることで、同じIDを2回入れようとすると DB が拒否します。「処理済みかを調べてから記録する」と2段階にするより、1回の挿入で決まるので、ほぼ同時に同じ通知が届いても二重に処理されません。

    名前を付けてマイグレーションを作り、適用します。

    npm run db:generate -- --name=webhook   # drizzle/0006_webhook.sql が作られる
    npm run db:migrate

    2. 署名を確かめる

    署名の確認は lib/webhook.ts の小さな関数にまとめました。Stripe の窓口は引数で受け取るので、テストでは通信なしで確かめられます。

    // lib/webhook.ts(抜粋)
    export function verifyStripeEvent(stripe: Pick<Stripe, "webhooks">, rawBody: string, signature: string | null, secret: string | undefined): Stripe.Event {
      if (!secret) throw new WebhookNotConfiguredError();
      if (!signature) throw new Error("stripe-signature ヘッダーがありません");
      return stripe.webhooks.constructEvent(rawBody, signature, secret);
    }

    3. 通知を受ける入口(Route Handler)

    Next.js では、app/api/stripe/webhook/route.ts のように route.ts を置くと、画面ではなく API の入口を作れます(Route Handler)。

    // app/api/stripe/webhook/route.ts
    import { getStripe } from "@/lib/payment";
    import { handleStripeEvent, verifyStripeEvent } from "@/lib/webhook";
    
    export const dynamic = "force-dynamic";
    
    // Stripe が支払い結果を知らせてくる入口。利用者のブラウザではなく Stripe のサーバーから呼ばれる。
    // ログイン不要で誰でも URL を叩けるので、本物かどうかは署名だけで判断する
    export async function POST(request: Request) {
      // 署名の計算には「届いた本文そのまま」が必要。request.json() で読むと文字列が変わり、署名が合わなくなる
      const rawBody = await request.text();
    
      let event;
      try {
        event = verifyStripeEvent(getStripe(), rawBody, request.headers.get("stripe-signature"), process.env.STRIPE_WEBHOOK_SECRET);
      } catch (error) {
        console.error("Stripe の通知の署名を確認できませんでした", error instanceof Error ? error.message : error);
        return Response.json({ error: "invalid signature" }, { status: 400 });
      }
    
      try {
        const outcome = await handleStripeEvent(event);
        if (outcome === "slot_lost" || outcome === "mismatch") {
          console.error(`要確認: ${event.id}(${event.type})の処理結果は ${outcome} です`); // 人が見る必要がある結果は、ログに必ず残す
        }
        return Response.json({ received: true, outcome });
      } catch (error) {
        // 2xx 以外を返すと Stripe が時間をおいて再送する。DB の一時的な不調ならここで拾い直せる
        console.error("Stripe の通知の処理に失敗しました", error);
        return Response.json({ error: "processing failed" }, { status: 500 });
      }
    }

    応答の返し分けも大切です。署名が不正なら 400(再送されても同じ結果なので拒否でよい)、こちらの処理が失敗したら 500(Stripe に再送してもらい、あとで成功させる)、成功なら 200 です。

    4. 通知を処理する:記録と確定を同じトランザクションで

    handleStripeEvent は、通知の記録と予約の更新を 同じトランザクション(途中で失敗したら全部なかったことにする単位)に入れます。更新の途中で失敗すれば、記録も取り消されるので、再送された通知をもう一度正しく処理できます。

    // lib/webhook.ts(抜粋)
    export async function handleStripeEvent(event: Stripe.Event, now: Date = new Date()): Promise<WebhookOutcome> {
      return getDb().transaction(async (tx) => {
        // 先にイベント ID を記録する。すでにあれば(二重に届いた)何も返らず、ここで終わる
        const inserted = await tx.insert(stripeEvents).values({ id: event.id, type: event.type }).onConflictDoNothing().returning({ id: stripeEvents.id });
        if (inserted.length === 0) return "duplicate";
    
        switch (event.type) {
          case "checkout.session.completed":
          case "checkout.session.async_payment_succeeded":
            return confirmPaidSession(tx, event.data.object, now);
          case "checkout.session.expired":
            return expireSession(tx, event.data.object);
          default:
            return "ignored";
        }
      });
    }

    扱う通知は3種類だけです。checkout.session.completed(決済ページでの手続き完了)、checkout.session.async_payment_succeeded(入金が遅れる支払い方法での入金確認)、checkout.session.expired(決済ページの期限切れ)。必要な種類だけを扱い、それ以外は記録して無視します。

    📰 出典:Stripe ドキュメント「Fulfill orders」(Checkout の注文処理)

    確定の本体は次のとおりです。

    // lib/webhook.ts(抜粋)
    async function confirmPaidSession(tx: Tx, session: Stripe.Checkout.Session, now: Date): Promise<WebhookOutcome> {
      // 画面に戻ってきた時点ではなく、Stripe が「支払い済み」と伝えたときだけ確定する
      if (session.payment_status !== "paid") return "unpaid";
    
      const id = Number(session.client_reference_id);
      if (!Number.isInteger(id)) return "not_found";
      const [r] = await tx.select().from(reservations).where(eq(reservations.id, id)).limit(1);
      if (!r) return "not_found";
    
      // 予約に結びつけた決済ページと一致し、請求した金額が支払われていることを確かめる
      if (r.stripeSessionId !== session.id || session.amount_total !== r.totalYen) return "mismatch";
    
      if (r.status === "confirmed") return "already_confirmed";
    
      if (r.status === "pending") {
        await tx.update(reservations).set({ status: "confirmed", paidAt: now }).where(and(eq(reservations.id, id), eq(reservations.status, "pending")));
        return "confirmed";
      }
      // …(期限切れ後の扱いは次の項)
    }

    client_reference_id は、第6回で決済ページを作るときに「どの予約の支払いか」を持たせておいた値です。更新の条件にも status = 'pending' を付けているので、別の処理が先に状態を変えていても上書きしません。

    5. 期限切れのあとに支払いが届いたとき

    期限切れの予約に支払いが届いた場合は、確定に戻せるかを DB に試させます。

    // lib/webhook.ts(抜粋)
      if (r.status === "expired") {
        // お金は入ったが仮予約の期限が先に切れていた。枠が空いていれば確定に戻し、他の人が取っていれば排他制約が止める。
        // 失敗しても外側のトランザクション全体を壊さないよう、SAVEPOINT(入れ子のトランザクション)の中で試す
        try {
          await tx.transaction(async (inner) => {
            await inner.update(reservations).set({ status: "confirmed", paidAt: now }).where(eq(reservations.id, id));
          });
          return "revived";
        } catch (error) {
          if (!isExclusionViolation(error)) throw error;
          await tx.update(reservations).set({ paidAt: now }).where(eq(reservations.id, id)); // 支払いの事実だけ残す(返金対象の目印)
          return "slot_lost";
        }
      }

    PostgreSQL は、エラーが起きたトランザクションをそのまま続けられません。そのため、失敗するかもしれない更新だけを入れ子のトランザクション(SAVEPOINT)の中で試し、制約違反なら支払い日時だけを残します。「支払い済みなのに確定していない予約」は、countPaidButNotConfirmed() で数えられます。運用では、この件数が0でないときに通知が飛ぶようにしておくと、返金漏れを防げます。

    ここまでの処理をまとめた lib/webhook.ts の全文です(新しく作るファイル)。

    lib/webhook.ts の全文(110行)
    // lib/webhook.ts
    import { and, eq, sql } from "drizzle-orm";
    import type Stripe from "stripe";
    import { getDb } from "./db";
    import { isExclusionViolation } from "./reservations";
    import { reservations, stripeEvents } from "./schema";
    
    export class WebhookNotConfiguredError extends Error {
      constructor() {
        super("STRIPE_WEBHOOK_SECRET が設定されていません(.env.example を参照)");
      }
    }
    
    // 通知が本当に Stripe から来たものか、署名で確かめる。
    // 署名は「届いた本文そのまま」から計算されるので、JSON に直したあとの値ではなく、文字列のままの本文を渡す。
    // 署名が合わない・古すぎる(既定で5分)通知は例外になる
    export function verifyStripeEvent(stripe: Pick<Stripe, "webhooks">, rawBody: string, signature: string | null, secret: string | undefined): Stripe.Event {
      if (!secret) throw new WebhookNotConfiguredError();
      if (!signature) throw new Error("stripe-signature ヘッダーがありません");
      return stripe.webhooks.constructEvent(rawBody, signature, secret);
    }
    
    export type WebhookOutcome =
      | "duplicate" // 処理済みの通知(何もしない)
      | "ignored" // このアプリが使わない種類の通知
      | "confirmed" // 仮予約を確定した
      | "already_confirmed" // すでに確定していた
      | "revived" // 期限切れのあとに支払いが届いたが、枠が空いていたので確定した
      | "slot_lost" // 期限切れのあとに支払いが届き、枠が埋まっていた(返金が必要)
      | "unpaid" // まだ支払いが済んでいない(コンビニ払い等)
      | "mismatch" // 金額や決済ページ ID が予約と合わない(確定せず、調べる)
      | "not_found"
      | "expired"; // 決済ページの期限切れで、仮予約を期限切れにした
    
    type Tx = Parameters<Parameters<ReturnType<typeof getDb>["transaction"]>[0]>[0];
    
    // 通知1件を処理する。「通知の記録」と「予約の更新」を同じトランザクションに入れるので、
    // 途中で失敗すれば記録ごと巻き戻り、Stripe の再送でやり直せる
    export async function handleStripeEvent(event: Stripe.Event, now: Date = new Date()): Promise<WebhookOutcome> {
      return getDb().transaction(async (tx) => {
        // 先にイベント ID を記録する。すでにあれば(二重に届いた)何も返らず、ここで終わる
        const inserted = await tx.insert(stripeEvents).values({ id: event.id, type: event.type }).onConflictDoNothing().returning({ id: stripeEvents.id });
        if (inserted.length === 0) return "duplicate";
    
        switch (event.type) {
          case "checkout.session.completed":
          case "checkout.session.async_payment_succeeded":
            return confirmPaidSession(tx, event.data.object, now);
          case "checkout.session.expired":
            return expireSession(tx, event.data.object);
          default:
            return "ignored";
        }
      });
    }
    
    async function confirmPaidSession(tx: Tx, session: Stripe.Checkout.Session, now: Date): Promise<WebhookOutcome> {
      // 画面に戻ってきた時点ではなく、Stripe が「支払い済み」と伝えたときだけ確定する
      if (session.payment_status !== "paid") return "unpaid";
    
      const id = Number(session.client_reference_id);
      if (!Number.isInteger(id)) return "not_found";
      const [r] = await tx.select().from(reservations).where(eq(reservations.id, id)).limit(1);
      if (!r) return "not_found";
    
      // 予約に結びつけた決済ページと一致し、請求した金額が支払われていることを確かめる
      if (r.stripeSessionId !== session.id || session.amount_total !== r.totalYen) return "mismatch";
    
      if (r.status === "confirmed") return "already_confirmed";
    
      if (r.status === "pending") {
        await tx.update(reservations).set({ status: "confirmed", paidAt: now }).where(and(eq(reservations.id, id), eq(reservations.status, "pending")));
        return "confirmed";
      }
    
      if (r.status === "expired") {
        // お金は入ったが仮予約の期限が先に切れていた。枠が空いていれば確定に戻し、他の人が取っていれば排他制約が止める。
        // 失敗しても外側のトランザクション全体を壊さないよう、SAVEPOINT(入れ子のトランザクション)の中で試す
        try {
          await tx.transaction(async (inner) => {
            await inner.update(reservations).set({ status: "confirmed", paidAt: now }).where(eq(reservations.id, id));
          });
          return "revived";
        } catch (error) {
          if (!isExclusionViolation(error)) throw error;
          await tx.update(reservations).set({ paidAt: now }).where(eq(reservations.id, id)); // 支払いの事実だけ残す(返金対象の目印)
          return "slot_lost";
        }
      }
    
      return "mismatch"; // cancelled(決済ページの作成に失敗して取りやめた予約)に支払いが届くことは通常ない
    }
    
    async function expireSession(tx: Tx, session: Stripe.Checkout.Session): Promise<WebhookOutcome> {
      // 決済ページの期限が切れた。支払い待ちのままの仮予約だけを期限切れにして、枠を返す
      const rows = await tx
        .update(reservations)
        .set({ status: "expired" })
        .where(and(eq(reservations.stripeSessionId, session.id), eq(reservations.status, "pending")))
        .returning({ id: reservations.id });
      return rows.length > 0 ? "expired" : "ignored";
    }
    
    // 支払いが済んでいるのに確定していない予約(返金の対象)を数える。運用の確認用
    export async function countPaidButNotConfirmed(): Promise<number> {
      const [row] = await getDb()
        .select({ n: sql<number>`count(*)::int` })
        .from(reservations)
        .where(and(sql`${reservations.paidAt} is not null`, sql`${reservations.status} <> 'confirmed'`));
      return row.n;
    }

    6. 仮予約の期限切れを定期的に片付ける

    第6回では、期限切れの仮予約を「予約を保存する直前」にだけ片付けていました。今回は、全スペース分をまとめて片付ける入口 app/api/cron/expire-holds/route.ts を足しました。外部のスケジューラー(Vercel Cron など)から定期的に呼ぶ想定です。

    // app/api/cron/expire-holds/route.ts
    import { expireStaleHolds } from "@/lib/reservations";
    
    export const dynamic = "force-dynamic";
    
    // 支払いのないまま期限が過ぎた仮予約を、定期的に「期限切れ」にする入口。
    // 外部のスケジューラー(Vercel Cron 等)から呼ぶ。合言葉(CRON_SECRET)が合わない呼び出しは断る
    export async function GET(request: Request) {
      const secret = process.env.CRON_SECRET;
      if (!secret || request.headers.get("authorization") !== `Bearer ${secret}`) {
        return Response.json({ error: "unauthorized" }, { status: 401 });
      }
      const expired = await expireStaleHolds();
      return Response.json({ expired });
    }

    誰でも呼べる URL なので、合言葉(CRON_SECRET)を持たない呼び出しは 401 で断ります。実際に定期実行へ登録する作業は、公開を扱う第11回で行います。なお、空き状況の表示は期限を見て除外しているので、片付けが遅れても二重予約にはなりません(第6回で確認済み)。

    全スペースの片付けで件数を返せるよう、lib/reservations.ts の expireStaleHolds を直します(+ が追加、- が削除)

    --- a/lib/reservations.ts
    +++ b/lib/reservations.ts
    @@ -20,9 +20,10 @@ export type InsertResult = { ok: true; id: number } | { ok: false; reason: "conf
     
     // 支払いのないまま期限が過ぎた仮予約を「期限切れ」にして、枠を空ける。
     // 排他制約は期限(現在時刻)を知らないので、状態を expired に変えて初めて枠が空く。
    -// 予約を保存する直前に、そのスペースの分だけ呼ぶ(全スペースをまとめて片付ける定期実行は第7回で足す)
    -export async function expireStaleHolds(now: Date = new Date(), spaceId?: number): Promise<void> {
    -  await getDb()
    +// 予約を保存する直前にも(そのスペースの分だけ)、定期実行の入口 app/api/cron/expire-holds からも(全スペース)呼ぶ。
    +// 戻り値は期限切れにした件数
    +export async function expireStaleHolds(now: Date = new Date(), spaceId?: number): Promise<number> {
    +  const rows = await getDb()
         .update(reservations)
         .set({ status: "expired" })
         .where(
    @@ -31,7 +32,9 @@ export async function expireStaleHolds(now: Date = new Date(), spaceId?: number)
             lt(reservations.holdExpiresAt, now),
             spaceId === undefined ? undefined : eq(reservations.spaceId, spaceId),
           ),
    -    );
    +    )
    +    .returning({ id: reservations.id });
    +  return rows.length;
     }
     
     // 保存の最終的な番人は DB の排他制約。重なる予約が先に入っていれば保存に失敗し、conflict を返す。

    .env.example に、通知の署名用シークレットと、定期実行の合言葉を足します(+ が追加、- が削除)

    --- a/.env.example
    +++ b/.env.example
    @@ -4,3 +4,7 @@ DATABASE_URL=postgres://yoyaku:yoyaku@localhost:5432/yoyaku
     STRIPE_SECRET_KEY=
     # 決済のあと戻ってくる自社サイトの URL(末尾のスラッシュなし)
     APP_URL=http://localhost:3000
    +# Stripe の Webhook の署名用シークレット(whsec_ で始まる)。手元では `stripe listen --forward-to localhost:3000/api/stripe/webhook` が表示する値
    +STRIPE_WEBHOOK_SECRET=
    +# 定期実行の入口(/api/cron/expire-holds)を呼べる人を限る合言葉。長いランダムな文字列にする
    +CRON_SECRET=

    動作確認の方法

    自動テスト

    tests/webhook.test.ts に16件のテストを足しました(DB に接続する部分は、DATABASE_URL があるときだけ実行されます)。

    • 署名: 正しい署名は通る。本文が1文字違う・別のシークレット・1時間前の署名・ヘッダーなし・シークレット未設定は拒否される
    • 確定: 支払い済みの通知で確定し、支払い日時が残る
    • 二重処理: 同じイベントIDが2回届いても、2回目は何もしない(支払い日時も上書きされない)
    • 照合: 金額が違う通知・別の決済ページの通知・未払いの通知では確定しない
    • 期限切れ: 決済ページの期限切れの通知で枠が空く。期限切れのあとに支払いが届いたとき、枠が空いていれば確定に戻り、埋まっていれば確定せず印だけ残る

    tests/webhook.test.ts の全文です(新しく作るファイル)。署名は Stripe のライブラリの generateTestHeaderString で、テスト用に作っています。

    tests/webhook.test.ts の全文(164行)
    // tests/webhook.test.ts
    // 署名の確認は DB なしで、通知の処理は DB につないで確かめる。DATABASE_URL が無い環境では DB の部分を飛ばす。
    import { eq } from "drizzle-orm";
    import Stripe from "stripe";
    import { afterAll, beforeAll, describe, expect, it } from "vitest";
    import { createDb } from "@/lib/db";
    import { HOLD_MINUTES } from "@/lib/payment";
    import { attachCheckoutSession, expireStaleHolds, insertReservation } from "@/lib/reservations";
    import { reservations, spaces, stripeEvents } from "@/lib/schema";
    import { jstDateTime } from "@/lib/slots";
    import { WebhookNotConfiguredError, countPaidButNotConfirmed, handleStripeEvent, verifyStripeEvent } from "@/lib/webhook";
    
    const stripe = new Stripe("sk_test_dummy"); // 通信はしない。署名の検証だけに使う
    const secret = "whsec_test_secret";
    
    describe("署名の確認", () => {
      const body = JSON.stringify({ id: "evt_1", object: "event", type: "checkout.session.completed", data: { object: {} } });
      const sign = (payload: string, timestamp = Math.floor(Date.now() / 1000)) =>
        stripe.webhooks.generateTestHeaderString({ payload, secret, timestamp });
    
      it("正しい署名なら通知を取り出せる", () => {
        expect(verifyStripeEvent(stripe, body, sign(body), secret).id).toBe("evt_1");
      });
    
      it("本文が1文字でも書き換えられていたら拒否する", () => {
        expect(() => verifyStripeEvent(stripe, body.replace("evt_1", "evt_2"), sign(body), secret)).toThrow();
      });
    
      it("別のシークレットで作られた署名は拒否する", () => {
        const forged = stripe.webhooks.generateTestHeaderString({ payload: body, secret: "whsec_other" });
        expect(() => verifyStripeEvent(stripe, body, forged, secret)).toThrow();
      });
    
      it("古すぎる署名(使い回し)は拒否する", () => {
        const old = Math.floor(Date.now() / 1000) - 60 * 60;
        expect(() => verifyStripeEvent(stripe, body, sign(body, old), secret)).toThrow();
      });
    
      it("署名ヘッダーが無い、またはシークレット未設定なら拒否する", () => {
        expect(() => verifyStripeEvent(stripe, body, null, secret)).toThrow();
        expect(() => verifyStripeEvent(stripe, body, sign(body), undefined)).toThrow(WebhookNotConfiguredError);
      });
    });
    
    const booking = { date: "2026-12-05", startHour: 10, hours: 2, attendees: 2, contactName: "テスト", contactEmail: "wh@example.com" };
    const range = { startsAt: jstDateTime("2026-12-05", 10), endsAt: jstDateTime("2026-12-05", 12) };
    const t0 = new Date("2026-12-01T00:00:00Z");
    let seq = 0;
    
    // Stripe から届く通知の形(必要な項目だけ)
    function sessionEvent(type: string, session: { id: string; reservationId: number; amount: number; paid?: boolean }): Stripe.Event {
      return {
        id: `evt_test_${++seq}_${Date.now()}`,
        type,
        data: { object: { id: session.id, client_reference_id: String(session.reservationId), amount_total: session.amount, payment_status: session.paid === false ? "unpaid" : "paid" } },
      } as unknown as Stripe.Event;
    }
    
    describe.skipIf(!process.env.DATABASE_URL)("支払い通知の処理(DB)", () => {
      const { db, client } = createDb();
      let spaceId = 0;
    
      beforeAll(async () => {
        const [row] = await db
          .insert(spaces)
          .values({ slug: "test-webhook", name: "通知テスト用", area: "テスト", description: "テスト用", capacity: 4, hourlyPriceYen: 1000 })
          .onConflictDoUpdate({ target: spaces.slug, set: { name: "通知テスト用" } })
          .returning({ id: spaces.id });
        spaceId = row.id;
      });
    
      afterAll(async () => {
        await db.delete(spaces).where(eq(spaces.slug, "test-webhook"));
        await client.end();
      });
    
      // 仮予約を作り、決済ページ ID を結びつけた状態にする
      async function pendingReservation(sessionId: string, r = range, startHour = 10) {
        await db.delete(reservations).where(eq(reservations.spaceId, spaceId));
        const saved = await insertReservation(spaceId, { ...booking, startHour }, r, 2000, undefined, t0);
        if (!saved.ok) throw new Error("setup");
        await attachCheckoutSession(saved.id, sessionId);
        return saved.id;
      }
      const statusOf = async (id: number) => (await db.select().from(reservations).where(eq(reservations.id, id)))[0];
    
      it("支払い済みの通知で、仮予約が確定になり支払い日時が残る", async () => {
        const id = await pendingReservation("cs_test_a");
        const outcome = await handleStripeEvent(sessionEvent("checkout.session.completed", { id: "cs_test_a", reservationId: id, amount: 2000 }), t0);
        expect(outcome).toBe("confirmed");
        const row = await statusOf(id);
        expect(row.status).toBe("confirmed");
        expect(row.paidAt).toEqual(t0);
      });
    
      it("同じ通知(同じイベント ID)が2回届いても、2回目は何もしない", async () => {
        const id = await pendingReservation("cs_test_b");
        const event = sessionEvent("checkout.session.completed", { id: "cs_test_b", reservationId: id, amount: 2000 });
        expect(await handleStripeEvent(event, t0)).toBe("confirmed");
        expect(await handleStripeEvent(event, new Date(t0.getTime() + 60_000))).toBe("duplicate");
        expect((await statusOf(id)).paidAt).toEqual(t0); // 2回目で支払い日時が上書きされない
      });
    
      it("イベント ID が別でも、確定済みの予約には何も起きない", async () => {
        const id = await pendingReservation("cs_test_c");
        await handleStripeEvent(sessionEvent("checkout.session.completed", { id: "cs_test_c", reservationId: id, amount: 2000 }), t0);
        expect(await handleStripeEvent(sessionEvent("checkout.session.async_payment_succeeded", { id: "cs_test_c", reservationId: id, amount: 2000 }), t0)).toBe("already_confirmed");
      });
    
      it("金額が予約と合わない通知では確定しない", async () => {
        const id = await pendingReservation("cs_test_d");
        expect(await handleStripeEvent(sessionEvent("checkout.session.completed", { id: "cs_test_d", reservationId: id, amount: 100 }), t0)).toBe("mismatch");
        expect((await statusOf(id)).status).toBe("pending");
      });
    
      it("別の決済ページの通知では確定しない", async () => {
        const id = await pendingReservation("cs_test_e");
        expect(await handleStripeEvent(sessionEvent("checkout.session.completed", { id: "cs_test_other", reservationId: id, amount: 2000 }), t0)).toBe("mismatch");
        expect((await statusOf(id)).status).toBe("pending");
      });
    
      it("支払いが済んでいない通知(コンビニ払い等)では確定しない", async () => {
        const id = await pendingReservation("cs_test_f");
        expect(await handleStripeEvent(sessionEvent("checkout.session.completed", { id: "cs_test_f", reservationId: id, amount: 2000, paid: false }), t0)).toBe("unpaid");
        expect((await statusOf(id)).status).toBe("pending");
      });
    
      it("決済ページの期限切れの通知で、仮予約が期限切れになり枠が空く", async () => {
        const id = await pendingReservation("cs_test_g");
        expect(await handleStripeEvent(sessionEvent("checkout.session.expired", { id: "cs_test_g", reservationId: id, amount: 2000, paid: false }), t0)).toBe("expired");
        expect((await statusOf(id)).status).toBe("expired");
        expect((await insertReservation(spaceId, booking, range, 2000, undefined, t0)).ok).toBe(true);
      });
    
      it("使わない種類の通知は記録だけして無視する", async () => {
        const event = { id: `evt_other_${Date.now()}`, type: "customer.created", data: { object: {} } } as unknown as Stripe.Event;
        expect(await handleStripeEvent(event, t0)).toBe("ignored");
        expect((await db.select().from(stripeEvents).where(eq(stripeEvents.id, event.id))).length).toBe(1);
      });
    
      it("期限切れのあとに支払いが届いても、枠が空いていれば確定に戻す", async () => {
        const id = await pendingReservation("cs_test_h");
        await expireStaleHolds(new Date(t0.getTime() + (HOLD_MINUTES + 1) * 60_000), spaceId);
        expect((await statusOf(id)).status).toBe("expired");
        expect(await handleStripeEvent(sessionEvent("checkout.session.completed", { id: "cs_test_h", reservationId: id, amount: 2000 }), t0)).toBe("revived");
        expect((await statusOf(id)).status).toBe("confirmed");
      });
    
      it("期限切れのあとに支払いが届き、枠が埋まっていたら確定せず、返金対象の目印だけ残す", async () => {
        const id = await pendingReservation("cs_test_i");
        await expireStaleHolds(new Date(t0.getTime() + (HOLD_MINUTES + 1) * 60_000), spaceId);
        const other = await insertReservation(spaceId, booking, range, 2000, undefined, new Date(t0.getTime() + (HOLD_MINUTES + 2) * 60_000)); // 別の人が同じ枠を取った
        expect(other.ok).toBe(true);
        expect(await handleStripeEvent(sessionEvent("checkout.session.completed", { id: "cs_test_i", reservationId: id, amount: 2000 }), t0)).toBe("slot_lost");
        const row = await statusOf(id);
        expect(row.status).toBe("expired");
        expect(row.paidAt).toEqual(t0);
        expect(await countPaidButNotConfirmed()).toBeGreaterThanOrEqual(1);
      });
    
      it("定期実行の期限切れ処理は、全スペースの対象を数えて返す", async () => {
        await pendingReservation("cs_test_j");
        expect(await expireStaleHolds(new Date(t0.getTime() + (HOLD_MINUTES + 1) * 60_000))).toBeGreaterThanOrEqual(1);
      });
    });
    docker compose up -d   # データベースを起動(起動済みなら不要)
    export DATABASE_URL=postgres://yoyaku:yoyaku@localhost:5432/yoyaku
    npm run lint && npm run typecheck && npm test
    npm run build

    検証コマンドの結果は、npm run lint・npx tsc --noEmit・npm run build が成功、npm test が75件すべて成功でした(PostgreSQL 16 に接続して実行)。

    開発環境での HTTP の確認

    本番ビルドを起動し、署名つきの通知を実際に HTTP で送って確かめました(開発環境での確認です)。

    • 不正な署名 → 400
    • 正しい署名 → 200(処理結果は confirmed。DB の状態が confirmed になり、支払い日時が入る)
    • 同じ通知をもう一度 → 200(処理結果は duplicate)
    • 合言葉なしで定期実行の入口を呼ぶ → 401、合言葉つき → 200

    Stripe 本体との結合は未確認

    この環境には有効な Stripe のテスト用の鍵がなく、実際の Stripe からの通知の受信は未確認です。ここまでの確認は、署名を含む通知を自前で作って送ったものです。お手元で試すときは、Stripe CLI の stripe listen --forward-to localhost:3000/api/stripe/webhook を動かし、表示される whsec_ で始まる値を .env の STRIPE_WEBHOOK_SECRET に入れてください。テスト用のカード番号(4242 で始まるもの)で支払うと、通知が届いて予約が確定するはずです。

    📰 出典:Stripe ドキュメント「テスト」

    つまずきやすい点・セキュリティ上の注意

    • 本文は request.text() で読む:request.json() で読んで文字列に戻すと、空白や並び順が変わり、署名が合わなくなります。
    • シークレットを間違えやすい:Stripe CLI が表示する値と、ダッシュボードで登録した通知先の値は別物です。環境ごとに別のシークレットになります。
    • 通知の処理を重くしない:Stripe は応答が遅いと再送します。今回は予約の更新だけの軽い処理です。確認メールの送信など時間のかかる処理は、次回以降は別の仕組みに任せる前提で作ります。
    • 確定したことを画面の表示だけで判断しない:完了画面は、通知が届く前に表示されることがあります。そのため今回は「数秒かかることがあります。読み込み直してください」と案内しました(自動更新は省いています)。
    • 本番運用で必要だが省略したこと:通知の失敗を知らせる監視、通知用 URL の IP 制限、通知が長期間届かなかった場合の照合(Stripe の API で支払い状況を引き直す処理)。

    発注者向けメモ:支払いと予約のずれを防ぐために、開発会社に確認したいこと

    支払いの確認は、画面に見えない部分だからこそ、作り方で品質の差が出ます。次の点を、見積もりや設計の段階で確認すると安心です。

    • ☐ 予約の確定を、決済サービスからの署名つき通知で行っているか(完了画面に戻っただけで確定していないか)
    • ☐ 同じ通知が2回届いても、二重に処理されない作りか
    • ☐ 通知の処理が失敗したとき、再送で復旧できるか。復旧できなかった分に気づく仕組み(アラート)があるか
    • ☐ 支払い済みなのに予約が確定していない状態(期限切れとの競合など)が起きたとき、誰が・どう返金するか決まっているか
    • ☐ 支払いの金額が、予約の金額と一致しているかを確かめているか
    • ☐ 決済サービスのテスト環境で、成功・失敗・期限切れ・再送のパターンを一緒に確認できるか

    開発会社への質問例です。

    • 「支払いの通知が届かなかった場合、予約はどうなりますか? 気づく仕組みはありますか?」
    • 「支払い後に予約の枠が埋まっていた場合の対応(返金の流れ)は、設計に入っていますか?」
    • 「決済サービスから届く通知の履歴は、あとから調べられるように残りますか?」

    工数やリスクが増える条件は、コンビニ払いや銀行振込など入金が遅れる支払い方法の追加、複数の決済サービスの併用、返金・一部返金の自動化、売上の会計システムへの連携などです。これらは別途見積もりが必要な範囲として、最初に「カードの1回払いのみ」で始めるのが堅実です。

    まとめと次回予告

    この回では、Stripe からの通知(Webhook)で仮予約を確定する仕組みを作りました。

    • 通知は署名で本物かを確かめ、本文は文字列のまま読む
    • イベントIDを DB に記録して、同じ通知は一度しか処理しない
    • 通知の金額・決済ページIDを予約と照らし合わせ、合わなければ確定しない
    • 期限切れのあとに届いた支払いは、排他制約に判断を任せて、確定に戻すか返金対象にする
    • 期限切れの仮予約を片付ける入口を、合言葉つきで用意する

    次回の【第8回】は「予約確認メールとキャンセル・返金」です。確定した予約の確認メールを送り、キャンセル規定にもとづいて返金を行う流れと、今回の「返金対象」の扱いを作ります。前の回は第6回 Stripeで支払いを受けるです。

    この連載の記事一覧

    この記事は連載「Next.jsで作るオンライン予約サービス」の1回です。連載のほかの回は次のとおりです(連載の一覧ページ)。

    システム制作・運用・保守のお問い合わせはこちら


      よかったらシェアしてね!
      • URLをコピーしました!
      • URLをコピーしました!

      この記事を書いた人

      株式会社THIRD HERO代表取締役 朝野貴朗
      Webシステム開発を中心に、toC向けサービスサイトの運営、ツール開発などを行ってまいりました。

      コメント

      コメント一覧 (3件)

      目次