← ブログに戻る
Billing公開日 2026-03-21· 12 分で読了

Next.js サブスク課金:実際に動く Webhook 契約

WangNan, author at Uncorne
著者 WangNan
発行 Uncorne · 更新 2026-10-09

多くのサブスクリプション課金チュートリアルは、ハッピーパスで止まります。チェックアウトセッションを作り、ブラウザをリダイレクトして完了、と。これはデモでは動きますが、顧客が支払い途中でタブを閉じた瞬間、決済事業者がイベントを再送した瞬間、あるいはテストが二度発火した瞬間に壊れます。本番の課金は、そうしたチュートリアルが飛ばした部分にこそあります。これは Uncorne が生成するアプリの背後にある契約——5 つの決済事業者を 1 つの検証・権限レイヤーにまとめるもの——と、各ルールの理由です。

Next.js サブスク課金の Webhook フロー
Next.js サブスク課金の Webhook フロー

ブラウザは真実の情報源ではない

リダイレクトの成功は事実ではなく、あくまでヒントです。顧客は支払った後、成功ページが読み込まれる前にタブを閉じるかもしれません。Webhook はリダイレクトより先に届く、二度届く、あるいは署名検証に失敗してまったく届かないこともあります。リダイレクトは見た目のサンクス画面以外の何ものでもない、と扱ってください。

データベースが唯一の真実の情報源であり、そこにサブスクリプション状態を書き込めるのは 1 つだけ——事業者からの検証済み Webhook です。それ以外(成功ページ、事業者 API のポーリング、サポート担当のメモ)は、このデータベースを読むだけです。これを逆にすると、支払っていない人にアクセスを与えたり、支払った人を締め出したりすることになります。Stripe 公式のサブスクリプション概要に対応すべきライフサイクルイベントが列挙されています。実務ルールは、扱うイベントを減らし、それぞれを正しく扱い、残りは黙って飲み込むではなく明示的に無視することです。

検証契約を正確に述べる

署名検証はルートが最初に行うことです。body の解析より前、データベースに触るより前、顧客データを含むログを書くより前です。この契約は書き留める価値があります。なぜなら逆にすると那是セキュリティバグであり、スタイルの好みではないからです。

  • 署名が欠落・無効・不正な形式 → 例外を投げる。ルートは 400 を返し、何も書き込まない。
  • 正しく署名済みだが処理不要なイベント → 空の結果と ignored フラグ付きで 200 を返す。
  • 既に見たイベント id → 書き込む前にスキップ。
  • 有効・未処理・要処理のイベント → 書き込み、同一トランザクションでイベント id を記録。

Uncorne アダプターの初期バージョンは、検証失敗時に空リストを返していました。これは偽装リクエストを 200 で認めていたことを意味します。検証失敗がルートを応答する前に例外を投げるよう変更しました。この交換はしないでください。200 は約束であり、Stripe の Webhook 署名ガイドに従って署名を確認した後にだけ返すべきものです。

export async function POST(req: Request) {
  const raw = await req.text();               // 生の body で検証する
  let event: ProviderEvent;
  try {
    event = verifyAndParse(raw, req.headers); // 署名不正で例外
  } catch {
    return new Response("invalid signature", { status: 400 });
  }
  if (shouldIgnore(event)) {
    return json({ ignored: true, handled: [] });
  }
  const fresh = await markSeen(event.id);     // 原子的挿入、重複なら false
  if (!fresh) return json({ ignored: true, duplicate: true });
  await applyPlanChange(event);               // customer -> plan を書き込む
  return json({ handled: [event.type] });
}

検証には生のリクエスト body を使い、再シリアライズしたオブジェクトは絶対に使わないでください。JSON のキー順序や空白は事業者や SDK バージョン間で安定しておらず、再シリアライズは正しい署名を無効化する古典的な原因です。req.text() で body を一度読み、そのバイト列をそのまま検証器へ渡し、その後にオブジェクトへ解析します。

Webhook 署名検証のシーケンス
Webhook 署名検証のシーケンス

冪等性はオプションではない

事業者は再送します。プランを付与する Webhook は、エンドポイントが遅い、500 を返す、タイムアウトした場合に再度配信されます。重複排除がなければ、2 回目の配信でユーザーの割り当てがリセットされたり、サブスクが二度延長されたり、ようこそメールが二通届いたりします。処理済みのイベント id を記録するテーブルを作りましょう。

create table webhook_events (
  provider   text not null,
  event_id   text not null,
  type       text not null,
  received_at timestamptz not null default now(),
  primary key (provider, event_id)
);

挿入がゲートです。競合時に false を返す原子的挿入を使い、true が返ったときだけ進みます。Supabase では onConflict 付きの upsert と競合処理分岐、ローカル SQLite では INSERT ... ON CONFLICT DO NOTHING の後に変更行数を確認します。DB が対応していれば、重複排除とプラン書き込みを同じトランザクションに入れ、クラッシュで「イベントは記録されたがプランは未変更」という状態が残らないようにします。行は事業者の再送ウィンドウより長く保持してください。Stripe は最大 3 日再送するので、30 日保持なら余裕があります。

権限はサーバーで、UI では決めない

ボタンを隠すことはアクセス制御ではありません。すべての保護ルートでセッションかデータベースからプランを読み、そこで判定します。App Router では、cookies() でセッション Cookie を読んで権限を照会するルートハンドラーまたは Server Action を使うべきであり、prop をチェックするクライアントコンポーネントではありません。プランが非アクティブなら、devtools で DOM を書き換えられようが、curl で直接 API を呼ばれようが、AI エンドポイントは 402 を返します。

export async function POST(req: Request) {
  const session = await getSession();
  if (!session?.user) return new Response("unauthorized", { status: 401 });
  const entitlement = await getEntitlement(session.user.id);
  if (!entitlement.active) {
    return Response.json({ code: "no_entitlement" }, { status: 402 });
  }
  return streamAnswer(req, session.user.id);
}

Server Actions とミューテーションも同様です。フォームを描画するコンポーネントではなく、アクション内部で認可します。クライアント側のチェックは使いやすさのため、サーバー側のチェックはセキュリティのためです。どちらか一方しかできないなら、サーバー側を選んでください。役に立つ習慣は、まずサーバー側のチェックを書き、UI を「すでに下された判定の反映」として扱うことです。

サーバー側プランゲートのフロー
サーバー側プランゲートのフロー

402 と 429 は別の答え

2 つの失敗モードは常に混同されます。402 は権限がないことを示します——有効なライセンス、アクティブなサブスク、確認済みのメールclaim がない。429 は顧客に権限はあるが利用枠を使い切ったことを示します。混ぜるとダッシュボードが誤解を招き、サポートが辛くなります。なぜなら片方の解法は「プランを買う」で、もう片方の解法は「リセットを待つ」だからです。

| ステータス | コード | 意味 | クライアントがすべきこと | | --- | --- | --- | --- | | 402 | no_entitlement | 有効なライセンス/サブスクがない | 請求ポータルを開く | | 402 | preview_limit_reached | 匿名プレビュー枠を使い切った | 登録を促す | | 429 | quota_exceeded | AI の日次枠を使い切った | リセット時刻を表示 | | 400 | invalid_signature | Webhook の署名検証失敗 | 何もしない——サーバー側のみ |

サブスク状態と利用制限は同じではありません。AI エンドポイントには独自のユーザーごとの日次枠(AI_MESSAGES_PER_DAY、既定 50)があり、Supabase RPC またはローカル SQLite の ai_usage テーブルで差し引かれます。使い切ったら、実際のリセット時刻から計算した正直な秒数の Retry-After と X-AI-Quota-Reset ヘッダーを付けて 429 を返してください。決め打ちの 86400 ではいけません。偽の再試行ヒントはないより悪く、クライアントにヘッダーを無視する癖を付け、サポートチームを推測させます。

1 つのチェックアウト契約、5 つの事業者

Uncorne は Waffo、Stripe、Creem、PayPal、Lemon Squeezy のアダプターを単一インターフェースの背後に提供します。各アダプターは事業者のイベントを小さな内部語彙——activated、renewed、cancelled、past due——にマッピングし、権限レイヤーはその語彙だけを理解します。すると事業者の切り替えは、設定変更と Webhook URL の更新だけで、製品コードの書き換えではありません。正規化すべきフィールド(customer id、subscription id、price id、現在の期間終了)の参考には Stripe Checkout Sessions API が最適です。

トレードオフも正直に述べます。共通契約は最小公倍数です。従量課金や Merchant of Record の税金処理といった事業者固有機能には、逃げ道が必要です。事業者固有データを載せるアダプターメソッドを残し、それが意図的に非ポータブルであると明記して、誰も「この抽象化は魔法だ」と思わないようにします。

1 つの契約の背後にある 5 つの決済アダプター
1 つの契約の背後にある 5 つの決済アダプター

返金、キャンセル、「アクティブ」の本当の意味

サブスクはあるシステムではアクティブでも、別のシステムでは返金済みかもしれません。サブスクイベントに加えて返金とチャージバックのイベントも監視し、全額返金は期間終了を待たず即座の無効化として扱います。キャンセルには cancel_at_period_end を優先してください。顧客は支払済みの期間中アクセスを維持でき、「初日でデータが消えた」というサポートチケットを避けられます。

事業者の生ステータスを自分たちの正規化した権限と並べて保存し、サインアップ時に一度設定した真偽値から「アクティブ」を推論しないでください。適用済みの最新イベントから読み取り時に再計算します。この一変更で、「DB ではプランが正しいのに製品では間違っている」という不思議なバグのクラスが直ります。

セキュリティ不変条件をオフラインでテストする

契約の検証に 5 つのサンドボックスアカウントは要りません。Uncorne にはオフライン署名プローブ npm run probe:webhook が同梱されており、稼働中のサーバーに 4 種類の body——正しい署名、署名なし、署名改ざん、不正な JSON——を送ります。上の表のステータスコードをアサートするので、「検証失敗なのに 200 を返す」という回帰は CI で落ちます。実際のサンドボックスが配信するイベント型は Stripe Webhooks ガイドに記載されているので、その一覧から E2E ケースを作ってください。

リアリズムの順に 4 層:

  1. 固定フィクスチャで検証関数を単体テスト。
  2. 稼働中の開発サーバーに対するオフラインプローブ——資格情報不要。
  3. 各事業者のテスト鍵によるサンドボックス E2E、実際の再送を含む。
  4. デプロイ後の小さなカナリア:低額のサブスクを 1 件作り、即座に返金。

1 層目と 2 層目は CI に置き、速く保ちます。3 層目と 4 層目は公開前のゲートです。オフライン層を飛ばすのがよくある間違いで、外部サービスに依存せずに「失敗時に 200 を返す」バグを捕まえられるのはここだけです。

オフライン Webhook プローブの出力
オフライン Webhook プローブの出力

設計で先回りすべき失敗シナリオ

忘れられやすいが実際に起きる状況がいくつかあります。更新 Webhook が遅れて届き、cron が先にアクセスを取り消していた——イベントを孤立させて適用するのでなく、事業者の現在状態から権限を再計算します。顧客がアップグレードし、2 つのサブスクイベントが順不同で届く——期間終了タイムスタンプを保存し、適用済みより古いイベントは無視します。署名は正しいが参照先の customer id がまだ存在しない——ドロップせず、ユーザー作成後に再試行するキューへ入れます。

可観測性も重要です。イベント id、種別、下した判定(handled、ignored、duplicate、failed)をハッシュ化した顧客 id と一緒にログへ出してください。生の body はログに残さないでください。個人情報や支払い手段のトークンが含まれる可能性があります。「支払ったのにまだ入れない」と言われたとき、どのイベントが届き、それぞれに何をしたかを 1 クエリで答えられるべきです。

公開前の短いチェックリスト

  • 生 body の署名検証は失敗時に例外を投げ、決して 200 を返さない。
  • 処理済みイベント id はプラン書き込み前に原子的に記録される。
  • 保護ルートはサーバーで権限を読み、クライアントだけのゲートがない。
  • 402 と 429 に安定した機械可読コードと正直な再試行ヘッダーがある。
  • オフラインプローブが全 PR の CI で動く。
  • 公開前に事業者ごとに 1 回以上のサンドボックス E2E を実施。

製品作成とチェックアウトルートの完全な手順は Next.js に Stripe サブスクを追加する方法を参照してください。テンプレート内で課金がどこに位置するかは Stripe と認証付き Next.js SaaS ボイラープレートで確認すべきことを参照してください。

サブスク課金が難しいのは API が難しいからではありません。エッジケースが実際の顧客に当たるまで見えないからです。契約を書き、不変条件をオフラインでテストし、アクセスを決めるのはブラウザではなく Webhook にしてください。

FAQ

ブラウザのリダイレクトだけで有料アクセスを付与してよいですか?+

いいえ。リダイレクトは支払いの証明ではなくヒントです。サブスク状態をデータベースに書き込めるのは検証済み Webhook だけにし、成功ページを含むそれ以外はすべてこの DB を読むだけにします。これで、支払わずにタブを閉じた人やコールバックを再生した人がアクセスを得るのを防げます。

Webhook を冪等にするには?+

事業者のイベント id を webhook_events テーブルに (provider, event_id) を主キーとして保存し、プランやライセンスを書く前に原子的挿入を行います。検証が先で、検証済み・未処理のイベントだけが重複排除に進みます。Stripe は最大 3 日再送するため、行は少なくとも 30 日保持してください。

サブスクアプリで 402 と 429 はどう違いますか?+

402 は権限がない状態——有効なライセンス、アクティブなサブスク、確認済みメールclaim がない。429 は権限はあるが AI 日次枠を使い切った状態です。プレビュー枠の枯渇は preview_limit_reached コードを持つ別の 402 です。402 はプラン購入、429 はリセット待ちで解消します。

Next.js で Webhook 署名をどう検証すべきですか?+

req.text() で生のリクエスト body を一度読み、そのバイト列をそのまま検証器へ渡してからオブジェクトに解析します。署名が欠落・無効・不正なら例外を投げ、ルートが 400 を返して何も書かないようにします。先に JSON を再シリアライズすると、キー順序や空白が変わるため正しい署名が無効になることがあります。

サンドボックス口座なしでサブスク課金をテストできますか?+

npm run probe:webhook で共通の検証契約をオフライン検証できます。稼働中のサーバーに合法・署名なし・署名改ざん・不正 JSON の 4 種を送りステータスコードをアサートします。ただし各ゲートウェイの実结账フローは公開前に各自のサンドボックス資格情報が必要です。4 層戦略は docs/payment-testing.md を参照してください。

よくある質問をすべて見る · Markdown 版(AI エージェント向け)