はじめに：この記事の前提と目的
以前、Stripeのサブスク運営をWebhookの２イベントで運用する記事を書きましたが、今回は少し安定させるために５イベント構成版の記事です。
この記事では、Stripeでサブスクリプション（定期課金）を運営する際に、どのWebhookイベントを最小限扱えばよいかを整理します。コードやAPIキーの扱い、デバッグ方法などの実装要素は含みません。目的は「設計レベルでStripeサブスク運営を理解する」ことです。
Stripeには数多くのWebhookイベントが存在しますが、すべてを受信する必要はありません。むしろ、目的に合わないイベントを多く登録すると、システムが複雑化し、管理コストが増してしまいます。本記事では、本当に必要な5つのイベントだけに絞り、その選定理由と役割を明確にします。
余談ですが、未使用のイベントを何らかの理由でリッスンする場合、HTTPレスポンスは200番を返すようにしてください。
400番を返すとStripe側のエラーログに記録されます。 使わないイベントはリッスンしない方がいいですが。
対象読者と想定シナリオ
この記事は、ノーコードまたはローコードでStripeを導入している、もしくはしようとしている個人事業主・中小企業・フリーランスエンジニアを想定しています。ダッシュボードでサブスクを管理しており、Webhook機能の存在は知っているが、どのイベントを選べばよいか迷っている方に向けた内容です。
今回は５イベントで運用する方法について書いていますが、さらに最小構成の２イベントで運用する方法もありますので、知りたい方は以下の記事を参考にしてください。 今回も前回同様、メール通知Stripeのものを、カスタマーポータルを利用することを前提にしています。
メール通知やサブスクの管理ページを自作すると処理が複雑になるためです。 あくまで初学者向けの内容です。
Webhookの役割とサブスク運営での位置づけ
StripeのWebhookは、Stripe側で発生した出来事（イベント）を外部システムに知らせる通知の仕組みです。たとえば、「顧客がサブスクを開始した」「請求が成功した」「契約がキャンセルされた」などの情報を、自分のシステムやノーコードツールへ届ける役割を持っています。
この通知によって、あなたのシステムは「いつ契約が始まり、いつ終了し、今どんな状態にあるのか」を正確に把握できるようになります。Webhookは、Stripeサブスク運営を自動化・安定化させるための中枢的な要素です。
なぜ非同期処理が発生するのか
サブスク課金の処理はすべてStripeのサーバー側で行われ、ユーザーの操作と実際の課金が時間差で発生することがあります。たとえば、カード決済が承認されるまでの間や、請求書が自動生成されるタイミングなどです。
このように、あなたのサブスクサービスが「今どの状態なのか」を知るには、Stripeからの通知（Webhook）が必要になります。Webhookは、Stripeの内部状態をあなたの外部アプリに同期するための“橋渡し”の役割を果たします。
手動運用との違いと限界
Webhookを使わずにダッシュボードだけで運営する場合、解約・更新・支払い失敗などを手動で確認する必要があります。少数の契約なら対応できますが、数が増えると「どの顧客が有効か」「請求が止まったか」を見落とすリスクが高まります。
Webhookを導入すれば、これらの状態変化をリアルタイムに自動で把握できます。
次章では、このWebhookの中から「5イベント」に絞り、その理由と構成全体を解説します。
最小Webhook構成の全体像（5イベントに絞る理由）
Stripeには100種類以上のWebhookイベントがありますが、すべてを受信する必要はありません。サブスク運営の本質は「契約の状態がどう変化したか」を追跡することにあります。よって、課金やキャンセルなどの状態を代表するイベントを数点押さえれば、運用として十分に成り立ちます。
ここでは、実務で最低限必要な5つのイベントだけに絞り込みます。これは、StripeのBilling（定期課金）で発生する代表的な状態変化をカバーする最小セットです。公式ドキュメントでも推奨されている基本構成であり、多くの中小規模サービスはこの範囲で運用可能です。
前提条件としてメール通知はStripeの機能を頼ること、契約できるサブスクは１ユーザー１つまで、契約内容の変更はカスタマーポータルを使うなどがありますが、最小構成でサブスクを回すことができます。
状態変化の整理（開始・更新・終了・成功・失敗）
サブスクのライフサイクルは、以下の5つの状態変化で説明できます。
- 開始： 顧客が新しくサブスクを申し込む
- 更新： プランや数量が変更される
- 終了： 契約がキャンセルまたは失効する
- 成功： 定期請求が成功する
- 失敗： 定期請求が失敗する
これらをそれぞれ表すイベントを選べば、全体の状態をほぼ漏れなく把握できます。StripeのWebhookは多くの情報を提供しますが、目的が「サブスクの状態追跡」であるなら、5種類で十分です。
選定基準：重複を避け、意味が明確なイベントのみ
Webhookイベントには似た意味を持つものが多く存在します。たとえば、payment_intent.succeeded と invoice.payment_succeeded はどちらも支払い成功を示します。しかし、サブスクの定期課金では後者（invoice）が一貫して使われるため、Intent系は除外します。
同様に、customer.subscription.created と checkout.session.completed は似ていますが、後者のほうが「顧客がCheckout経由で契約を完了した」ことを確実に把握できます。このように、重複を避けて意味が一意なイベントを選ぶことが「最小構成」の基本方針です。
結果として、Stripeサブスク運営に必要なのは次の5イベントです。
checkout.session.completedcustomer.subscription.updatedcustomer.subscription.deletedinvoice.payment_succeededinvoice.payment_failed
次の章では、それぞれのイベントの役割と、どのような状態変化を意味するのかを詳しく見ていきます。
必要最小限のWebhookイベントと役割
ここからは、選定された5つのイベントそれぞれが何を意味し、どのような運用上の役割を持つかを解説します。技術的な実装やコード例は扱わず、「どのイベントがどの状態を伝えてくれるのか」という概念的な理解を目的とします。
checkout.session.completed：新規契約の開始
顧客がCheckoutページでサブスクを申し込み、最初の支払いを完了したときに発火します。これが「契約開始」の確定サインです。customer.subscription.created よりも実務的で、確実に支払いが完了してから契約を有効化できます。
このイベントを受けた時点で、アプリやツール側では「新規会員登録」「初回アクセス権の付与」などの初期化を行う設計を考えます。 その際に注意するのが、このイベントは以下の３つの条件でも発生する点です。
初回サブスクリプション契約完了
保存済み顧客が再契約
クレカ情報の更新成功（支払い方法変更）
特に「クレカ情報の更新成功」ではサブスクを有効にする処理は必要がないため、webhook eventsオブジェクト内の「mode」が「subscription」であることを確認してください。
初回時は自社ＤＢ側では、顧客のサブスクを有効にするタイミングに使います。
customer.subscription.updated：サブスクの契約変更
customer.subscription.updated は、既存契約に変更があった際（プラン変更、数量変更、キャンセル予約など）に発火します。Stripeは契約中に複数回このイベントを送ることがありますが、「何が変わったか」の差分を見れば十分です。
キャンセル予約が入った場合は次の更新日で、「customer.subscription.deleted」が発生します。
customer.subscription.deleted：サブスクの契約終了
customer.subscription.deleted は、契約が完全に終了したことを示す明確な通知です。キャンセルが予定された時点ではupdatedが、実際に解約されたタイミングではdeletedが届く、という関係です。これにより、「いつ終了したか」を正確に捉えられます。
自社ＤＢ側では、顧客のサブスクを無効にするタイミングに使います。
invoice.payment_succeeded：支払い完了
サブスクは継続課金が前提です。毎月または毎期間の支払いが成功したかどうかを知ることが、継続利用の可否を決定する鍵となります。
invoice.payment_succeeded — 支払い成功。アクセス権や契約期間の延長を反映するタイミング。
初回・更新時の支払い完了のイベント時に発生するイベントです。
自社ＤＢ側では、顧客のサブスク状態を更新する場合に使います。
invoice.payment_failed：支払い失敗
invoice.payment_failed — 支払い失敗。顧客に再試行を促す、あるいは一時的にサービスを停止する判断を行うための情報。
システムの設計にもよりますが、初回決済時で発生した場合にはsubscriptionのstatusが「incomplete」になったままになりますので、確認処理を入れると安定します。
これらを受信することで、顧客ごとの「利用可能・保留・停止」といった状態管理を自動化できます。これ以上のイベントを追加しなくても、請求と契約の整合性を保つことが可能です。
次章では、これらの5イベントがどのように時系列でつながり、サブスク全体のライフサイクルを形成しているかを見ていきます。
イベントがつなぐ「契約のライフサイクル」
これまで紹介した5つのWebhookイベントは、それぞれがサブスクリプション契約の状態を表す「節目」のような存在です。Stripeでは顧客の行動や課金処理が非同期で進むため、これらのイベントを時系列で受け取ることで、契約全体のライフサイクルを追跡できます。
1契約の流れを時系列で追う
以下は、1人の顧客がサブスクを開始して解約に至るまでの典型的な流れを、Webhookイベントの順に並べたものです。
- checkout.session.completed： 顧客がCheckoutで支払いを完了し、契約が開始。
- invoice.payment_succeeded： 最初の請求が成功。初回アクセス期間が有効化。
- customer.subscription.updated： 顧客がプラン変更やキャンセル予約を行う。
- invoice.payment_failed： 継続課金で決済失敗。リトライまたは停止検討。
- customer.subscription.deleted： 解約が確定。契約終了を反映。
これらのイベントを受けることで、契約の「開始→継続→変更→終了」までの一連の流れを把握できます。たとえば支払い失敗が連続した場合、システム側でアラートやステータス変更を行う設計も可能です。
ただ、メールに関してはStripeのを使うので、状況を把握しているだけで大丈夫です。
どのタイミングで状態を更新すべきか
重要なのは「どのイベントを、どの状態の更新トリガーにするか」を明確にすることです。たとえば次のようなルールを設けると運用が安定します。
- 契約の開始：
checkout.session.completedを受信した時点で有効化。 - プラン変更やキャンセル予約：
customer.subscription.updatedを反映。 - 契約終了：
customer.subscription.deletedで終了状態に変更。 - 課金成功：
invoice.payment_succeededでアクセス期間を延長。 - 課金失敗：
invoice.payment_failedでステータスを「支払い保留」に。
このように、各イベントを状態遷移モデルに紐づけることで、後からコード化する際にも矛盾のない設計になります。Webhookは単なる通知ではなく、「システムを動かすタイミング」を定義する指標と考えるとわかりやすいでしょう。
設計のヒント：イベントをどう扱うか
Webhookを活かす設計とは、「どのイベントが来たときに、どんな意味づけをするか」を整理することです。特にStripeのサブスク運営では、イベントを正しく“分類”することで自動化の精度が大きく向上します。
状態モデルをもとにWebhookを設計する
おすすめは、まず「契約状態のマップ」を作成することです。たとえば「未契約 → 有効 → 保留 → 終了」といった状態を定義し、どのイベントでどの状態に遷移するかを表にまとめます。
このように状態を視覚化しておくと、ノーコードツールやスクリプトでWebhookを受け取る際も混乱がありません。「どのイベントがどの列を更新するか」が明確になるからです。
Stripeのイベントは一見似ているものが多いですが、「状態を変えるイベントだけを聴く」という考え方に立つと、必要最小限に整理できます。
ノーコード・ローコード運用での応用例
Webhookはプログラミングを行わなくても扱えます。たとえば、Make（旧Integromat）やZapierなどのノーコードツールでは、Webhookトリガーを受け取り、GoogleスプレッドシートやAirtableに契約情報を自動記録することが可能です。
次のような構成が典型的です：
checkout.session.completedで新しい行を追加（新規契約）。invoice.payment_succeededで「有効期間」を更新。invoice.payment_failedで「ステータス」を「支払い保留」に変更。customer.subscription.deletedで「契約状態」を「終了」に変更。
これだけで、サブスクの基本的な運用がノーコードで成立します。WebhookはAPI連携の知識がなくても使える“自動通知”の仕組みであり、シンプルなルール設計から始めても十分効果があります。
次章では、こうした設計にまつわるよくある誤解や、イベント選定時の注意点を紹介します。
よくある誤解と注意点
StripeのWebhookは一見シンプルに見えますが、イベントが多岐にわたるため「どれを使うべきか」で混乱するケースが少なくありません。ここでは、初期設定や運用設計の段階でよくある誤解と、その注意点をまとめます。
PaymentIntentイベントを聴く必要は？
Stripeの公式ドキュメントには payment_intent.succeeded などのイベントも多く登場しますが、サブスク運営ではこれらを個別に受け取る必要はほとんどありません。なぜなら、定期課金の支払いはすべて請求書（Invoice）を通して管理されるため、invoice.payment_succeeded と invoice.payment_failed を聴いていれば支払い状況を完全に把握できるからです。
PaymentIntentイベントは一度きりの支払い（単発課金）や、Checkout以外のカスタムフローを実装するときに用います。サブスクに特化した構成では混乱を避けるためにもIntent系イベントを省くのが無難です。
trial_will_endを入れるかどうかの判断
customer.subscription.trial_will_end は、トライアル期間が終了する数日前に通知されるイベントです。メール通知やアプリ内バナーなどで「まもなく課金が始まります」と知らせたい場合に役立ちます。
ただし、トライアルを設けていないサービスや、顧客が即時課金で開始する場合には不要です。つまり、このイベントは「ユーザーに事前告知が必要かどうか」で判断します。最小構成では必須ではありませんが、顧客体験の向上を狙う場合に追加を検討してもよいでしょう。
運用時の確認ポイント（公式仕様の更新）
Stripeは頻繁に新しいイベントを追加・変更しています。特にBilling領域では、新しい支払い方法や税設定の登場に伴い、イベント構造が更新されることがあります。運用中のWebhookが急に挙動を変えることはありませんが、数ヶ月に一度は公式ドキュメントで最新の仕様を確認することをおすすめします。
また、Stripe ダッシュボードでは実際に受信したイベント履歴を閲覧できるため、設定したWebhookが想定どおり動作しているかをチェックできます。実装フェーズに入る前でも、この画面を眺めておくと「どんなイベントが発生するのか」の理解が深まります。
イベントを増やしすぎない
Webhookの受信イベントを多く設定しすぎると、管理が煩雑になりやすくなります。不要なイベントが増えると、どの通知が本当に重要なのかを見分けにくくなり、後から運用コストが跳ね上がります。まずは本記事で紹介した5つの最小構成で始め、必要が生じた時に追加する方が安全です。
Webhookは「すべてを聴く」ための仕組みではなく、「必要な変化だけを聴く」仕組みです。特にサブスク運営では、イベントを絞り込むことが安定運用の第一歩になります。
まとめ：Webhook設計の考え方を整理
この記事で紹介した内容をまとめると、Stripeサブスク運営におけるWebhook設計の基本は次のとおりです。
- Webhookは「Stripe内の状態変化を知るための通知」である。
- サブスク運営では、状態を表す5つのイベントでカバーできる。
- コード実装の前に「どのイベントが何を意味するか」を理解することが重要。
- トライアル通知などの追加イベントは、顧客体験を補う目的で検討する。
- 運用中は定期的に公式ドキュメントを確認し、仕様変更に備える。
WebhookはStripeサブスク運営の「裏側の神経」と言える存在です。コードをまだ書かない段階でも、今回紹介した5イベントの流れと意味を理解しておくだけで、将来の拡張や自動化がぐっとスムーズになります。
今後Webhookを活用してアクセス制御やメール配信、自動請求管理を行う場合も、この最小構成を土台に設計を広げていくことができます。
最終的にはメール通知を自社オリジナル文章にしたり、ユーザーごとのサブスク管理ページを作成させることもできます。
その第一歩としてこの記事がお役にたてれば嬉しいです。
コメント