サブスクリプションで Webhook を使用する

Webhook を使用して、サブスクリプションのアクティビティ通知を受信する方法をご紹介します。

Webhook イベントを通じて、アプリで Stripe の通知を受け取ります。ほとんどのアクティビティは非同期で行われるため、Webhook イベントを使用してサブスクリプションを管理します。これらのイベントは Webhook エンドポイント、または作成したイベントの送信先 (Amazon EventBridge など) で処理されます。

サブスクリプションでの Webhook の使用:

アプリに Webhook エンドポイントを作成します。
Workbench で Webhook エンドポイントを登録する
Stripe イベントを処理するロジックを追加します。サブスクリプションの場合、支払いの失敗やサブスクリプションのステータス変化 (トライアルからアクティブへの移行など) が対象です。Webhook クイックスタートガイドを参照して、Webhook エンドポイントを必要最低限の数で構築できます。
Webhook エンドポイントをテストして、想定どおりに動作していることを確認します。

アプリケーションが AWS で実行されている場合は、AWS アカウントの AWS EventBridge にイベントを直接送信するように Stripe を設定できます。

サブスクリプションイベント

Stripe は、サブスクリプションが作成または変更されるたびに、Events (イベント) をトリガーします。一部のイベントはサブスクリプションが作成されるとただちに送信され、その他のイベントは一定の請求間隔で発生します。

システムでイベントが適切に処理されていることを確認してください。たとえば、支払いが失敗した場合に顧客にメールを送信したり、サブスクリプションがキャンセルされたときに顧客のアクセス権を取り消したりすることができます。

次の表は、サブスクリプションに関連する最も一般的なイベントについて説明したものであり、該当する場合は、イベントを処理するためのアクションを提示しています。



`customer.created`	Customer (顧客)の作成に成功すると送信されます。
`customer.subscription.created`	サブスクリプションが作成されると送信されます。支払いを完了するために顧客の認証が必要な場合、または `payment_behavior` を `default_incomplete` に設定した場合、サブスクリプションの `status` が `incomplete` になります。詳しくは、サブスクリプションの支払い処理をご覧ください。
`customer.subscription.deleted`	顧客のサブスクリプションが終了すると送信されます。
`customer.subscription.paused`	サブスクリプションの `status` が `paused` に変わると送信されます。たとえば、支払い方法が指定されないまま無料トライアルが終了した場合に一時停止するようサブスクリプションが設定されている場合に送信されます。サブスクリプションが再開されるまで請求書は作成されません。支払いの回収が一時停止されている場合、その期間中も請求書は引き続き作成されるため、このイベントは送信されません。
`customer.subscription.resumed`	以前に `paused` ステータスであったサブスクリプションが再開されると送信されます。支払いの回収の一時停止が解除された場合は、これに該当しません。
`customer.subscription.trial_will_end`	トライアル期間終了の 3 日前に送信されます。トライアル期間が 3 日未満の場合、このイベントがトリガーされます。
`customer.subscription.updated`	サブスクリプションが開始または変更された場合に送信されます。たとえば、サブスクリプションの更新、クーポンの追加、割引の適用、請求書アイテムの追加、プランの変更はすべて、このイベントのトリガーとなります。
`entitlements.active_entitlement_summary.updated`	顧客の有効なエンタイトルメントが更新されると送信されます。このイベントを受け取ると、商品の機能へのアクセスをプロビジョニングまたはデプロビジョニングすることができます。エンタイトルメントの導入の詳細をご覧ください。
`invoice.created`	新規または更新済みのサブスクリプションに対して請求書が作成されると送信されます。Stripe で `invoice.created` に対する成功レスポンスを受信できない場合、自動請求で指定されたすべての請求書の確定が最大 72 時間遅延します。詳しくは、請求書の確定をご覧ください。 Finalize an Invoice (請求書の確定) API にリクエストを送信することで通知に応答します。
`invoice.finalized`	請求書の確定に成功し、支払いの準備が整うと送信されます。顧客に請求書を送信できます。詳しくは、請求書の確定をご覧ください。設定に応じて、Stripe は自動的にデフォルトの支払い方法に請求するか、回収を試みます。詳しくは、確定後のメールをご覧ください。
`invoice.finalization_failed`	請求書を確定することができませんでした。ガイドを参照して、請求書の確定失敗を処理する方法をご確認ください。請求書の概要ガイドに記載されている請求書の確定を確認してください。 Invoice の last_finalization_error を調べて、エラーの原因を判別します。 Stripe Tax を使用している場合、Invoice オブジェクトの automatic_tax フィールドを確認します。 `automatic_tax[status]=requires_location_inputs` の場合、請求書を確定させることはできず、支払いを回収できません。顧客に通知し、必要な顧客の場所を収集します。 `automatic_tax[status]=failed` の場合、後でリクエストを再試行します。
`invoice.paid`	請求書の支払いに成功すると送信されます。このイベントを受け取り、サブスクリプションの `status` が `active` になると、商品へのアクセスを提供できます。
`invoice.payment_action_required`	請求書に顧客の認証を必要とする場合に送信されます。請求書でアクションが必要な場合にサブスクリプションを処理する方法をご紹介します。
`invoice.payment_failed`	請求書に対する支払いが失敗しました。PaymentIntent のステータスは `requires_action` に変わります。サブスクリプションのステータスは、サブスクリプションの最初の請求書に対して「のみ」`incomplete` のままになります。支払いが失敗した場合、以下のような処理を行います。顧客に通知します。サブスクリプションの設定を構成し、Smart Retries とその他の売上回収機能を有効にする方法をご紹介します。 PaymentIntent を使用している場合、新しい支払情報を収集し、PaymentIntent を確定します。サブスクリプションの default payment method (デフォルトの支払い方法) を更新します。
`invoice.upcoming`	サブスクリプションの更新の数日前に送信されます。何日前に送信されるかについては、ダッシュボードの次回の更新イベントに設定された数値を参照します。既存のサブスクリプションについては、日数の変更は次の請求期間から有効になります。必要に応じて、追加の請求書アイテムを加えることもできます。
`invoice.updated`	支払いが成功または失敗したときに送信されます。支払いが成功の場合には、`paid` 属性が `true` に、`status` が `paid` に設定されます。支払いが失敗の場合には、`paid` が `false` に、`status` は `open` のままになります。また、支払いの失敗は、`invoice.payment_failed` イベントもトリガーします。
`payment_intent.created`	PaymentIntent が作成されると送信されます。
`payment_intent.succeeded`	PaymentIntent が正常に支払いを完了すると送信されます。
`subscription_schedule.aborted`	サブスクリプションスケジュールが、支払いの滞納により関連するサブスクリプションが終了となったことが原因でキャンセルされた場合に送信されます。
`subscription_schedule.canceled`	サブスクリプションスケジュールがキャンセルされ、それに関連するアクティブなサブスクリプションもキャンセルされた場合に送信されます。
`subscription_schedule.completed`	サブスクリプションスケジュールのすべてのフェーズが完了した場合に送信されます。
`subscription_schedule.created`	新しいサブスクリプションスケジュールが作成された場合に送信されます。
`subscription_schedule.expiring`	サブスクリプションスケジュールが無効になる 7 日前に送信されます。
`subscription_schedule.released`	サブスクリプションスケジュールがサブスクリプションからリリースされたとき、または停止され関連付けが解除されたときに送信されます。サブスクリプションはその後も残ります。
`subscription_schedule.updated`	サブスクリプションスケジュールが更新された場合に送信されます。

支払いの失敗を処理する

イベントは、Stripe がサブスクリプションの請求書の支払い失敗を通知するために利用する信頼性の高い方法です。支払い失敗のケースには一時的なものもあり、たとえば、カード発行会社が最初の支払いを拒否しているにもかかわらず、自動再試行を許可した場合などにこの一時的な支払い失敗が発生します。それ以外の支払い失敗は最終的なもの (例: 顧客が使用できる決済手段がないなど) であり、アクションが必要です。

イベント説明

イベント	説明
`invoice.payment_failed`	請求書の支払いが失敗しました。PaymentIntent のステータスが `requires_payment_method` になり、サブスクリプションのステータスは `incomplete` になります。支払いの失敗があった場合、以下の対応を検討してください。顧客に通知します。 PaymentIntents を使用している場合、新しい支払情報を収集し、PaymentIntent を確定します。サブスクリプションのデフォルトの支払い方法を更新します。 Smart Retries を有効にすることを検討してください。

invoice.payment_failed

請求書の支払いが失敗しました。PaymentIntent のステータスが requires_payment_method になり、サブスクリプションのステータスは incomplete になります。支払いの失敗があった場合、以下の対応を検討してください。

顧客に通知します。
PaymentIntents を使用している場合、新しい支払情報を収集し、PaymentIntent を確定します。
サブスクリプションのデフォルトの支払い方法を更新します。
Smart Retries を有効にすることを検討してください。

追加のアクションが必要な支払いを処理する

支払い方法によっては、顧客認証のような追加手順の完了が必要になることがあります。こうしたイベントを受け取ったら、お客様のアプリから顧客に対して、必要な対応を行うように通知する必要があります。追加措置が必要なイベントを処理する方法については、サブスクリプション概要ガイドをご覧ください。

イベント説明

イベント	説明
`invoice.finalization_failed`	請求書を確定することができませんでした。ガイドを参照して、請求書の確定失敗を処理する方法を確認してください。請求書概要ガイドの請求書の確定に関する詳細を確認してください。 Invoice の last_finalization_error を調べて、エラーの原因を判別します。 Stripe Tax を使用している場合、Invoice オブジェクトの automatic_tax フィールドを確認します。 `automatic_tax[status]=requires_location_inputs` の場合、請求書を確定させることはできず、支払いを回収できません。顧客に通知し、必要な顧客の場所を収集します。 `automatic_tax[status]=failed` の場合は、後でリクエストを再試行してください。
`invoice.payment_failed`	請求書の支払いが失敗しました。PaymentIntent のステータスが `requires_action` になり、サブスクリプションのステータスは `incomplete` になります。支払いの失敗があった場合、以下の対応を検討してください。顧客に通知します。 PaymentIntents を使用している場合、新しい支払情報を収集し、PaymentIntent を確定します。サブスクリプションのデフォルトの支払い方法を更新します。 Smart Retries を有効にすることを検討してください。
`invoice.payment_action_required`	請求書の支払いが失敗しました。PaymentIntent のステータスが `requires_action` になり、サブスクリプションのステータスは `incomplete` になります。支払いの失敗があった場合、以下の対応を検討してください。顧客に通知します。 PaymentIntents を使用している場合、新しい支払情報を収集し、PaymentIntent を確定します。サブスクリプションのデフォルトの支払い方法を更新します。 Smart Retries を有効にすることを検討してください。

invoice.finalization_failed

請求書を確定することができませんでした。ガイドを参照して、請求書の確定失敗を処理する方法を確認してください。請求書概要ガイドの請求書の確定に関する詳細を確認してください。

Invoice の last_finalization_error を調べて、エラーの原因を判別します。
Stripe Tax を使用している場合、Invoice オブジェクトの automatic_tax フィールドを確認します。
automatic_tax[status]=requires_location_inputs の場合、請求書を確定させることはできず、支払いを回収できません。顧客に通知し、必要な顧客の場所を収集します。
automatic_tax[status]=failed の場合は、後でリクエストを再試行してください。

invoice.payment_failed

請求書の支払いが失敗しました。PaymentIntent のステータスが requires_action になり、サブスクリプションのステータスは incomplete になります。支払いの失敗があった場合、以下の対応を検討してください。

顧客に通知します。
PaymentIntents を使用している場合、新しい支払情報を収集し、PaymentIntent を確定します。
サブスクリプションのデフォルトの支払い方法を更新します。
Smart Retries を有効にすることを検討してください。

invoice.payment_action_required

顧客に通知します。
PaymentIntents を使用している場合、新しい支払情報を収集し、PaymentIntent を確定します。
サブスクリプションのデフォルトの支払い方法を更新します。
Smart Retries を有効にすることを検討してください。

有効なサブスクリプションを追跡する

サブスクリプションでは、お客様のサイトと Stripe 間の調整が必要であり、顧客の継続支払いが成功するか失敗するかによって、顧客が製品やサービスに引き続きアクセスできるかどうかが決まります。

一般的なシステムの場合、顧客がサブスクリプションを登録したときに顧客の認証情報と、その顧客のアクセス有効期限を表すマッピングされたタイムスタンプ値がサイトに保存されます。顧客のログイン時に、タイムスタンプが将来の日付になっているかを確認してください。顧客がログインしたときのタイムスタンプが将来の日付である場合、そのアカウントは有効であり、顧客は引き続きサービスにアクセスできます。

サブスクリプションが更新されると、Stripe は登録されている顧客の決済手段に自動請求するか、または顧客に請求書をメールで送付して支払いの回収を試みます。Stripe は Webhook イベントを送信して、お客様のサイトに請求書のステータスを通知します。

サイトが invoice.paid イベントを受信します。
- 決済手段に自動請求する場合、更新の数日前にお客様のサイトは、設定した Webhook エンドポイントへの invoice.upcoming イベントを受信します。このイベントをリッスンして、次の請求書に請求書項目を追加することができます。collection_method=send_invoice の場合、Stripe は invoice.upcoming イベントを送信しません。
アプリケーションは、支払い済みの顧客を検索します。
アプリケーションは、データベース内の顧客のアクセス有効期限を将来の適切な日付 (1 日または 2 日の猶予期間あり) に更新します。

サブスクリプションのステータス変化を検出する

次の表で説明するサブスクリプションステータスの移行が、システムで適切に監視・処理されていることを確認してください。

一部のステータス変更には特別な注意が必要です。

トライアル期間が終了し、サブスクリプションが trialing から active に移行する数日前に、customer.subscription.trial_will_end イベントが送信されます。このイベントを受け取ったら、顧客に請求するための決済手段が顧客にあるか確認します。必要に応じて、今後請求されることを顧客に通知します。
サブスクリプションが past_due に移行すると、顧客に直接通知し、支払い詳細を更新するように依頼します。Stripe はこのプロセスを自動化するのに役立ついくつかの機能を提供しています。売上回収についてご確認ください。
サブスクリプションが canceled または unpaid に変更されたら、製品へのアクセスを取り消します。

ステータス	説明
`trialing`	サブスクリプションは現在トライアル期間中であり、顧客にプロダクトを支障なく提供できます。初回の支払いが行われると、サブスクリプションは自動的に `active` に移行します。
`active`	サブスクリプションは良好な状態です。`past_due` のサブスクリプションの場合、関連する請求書への最新の支払いまたは回収不能という判定によって、サブスクリプションは `active` に移行します。`active` は、サブスクリプションに関連するすべての未払いの請求書が支払われたことを示しているわけではないことに注意してください。その他の未払いの請求書は、支払い対象として残すか、回収不能と判定するか、必要に応じて無効化することができます。
`incomplete`	サブスクリプションを有効にするには、顧客が 23 時間以内に支払いを成功させる必要があります。または、支払いで顧客認証などの対応が必要です。保留中の支払いがあり、PaymentIntent のステータスが `processing` の場合も、サブスクリプションが `incomplete` になることがあります。
`incomplete_expired`	サブスクリプションの初回の支払いが失敗し、サブスクリプションの作成から 23 時間以内に支払いが成功しませんでした。これらのサブスクリプションは顧客に請求されません。このステータスは、サブスクリプションの有効化に失敗した顧客を追跡するために存在します。
`past_due`	最新の「確定済み」の請求書の支払いが失敗したか、試行されていません。サブスクリプションでは、引き続き請求書が作成されます。サブスクリプションのその後の状態は、サブスクリプションの設定によって決まります。Smart Retries をすべて試行しても請求書が未払いの場合は、サブスクリプションを `canceled` または `unpaid` に移行するか、`past_due` のままにすることができます。サブスクリプションを再度有効にするには、顧客に最新の請求書の支払いを依頼します。支払いが最新の請求書の期日前または後のどちらで行われたかに関係なく、サブスクリプションのステータスは `active` になります。
`canceled`	サブスクリプションがキャンセルされました。キャンセル時に未払いのすべての請求書の自動回収が無効化されます (`auto_advance=false`)。これは、更新できない最終的なステータスです。
`unpaid`	最新の請求書は支払われていませんが、サブスクリプションはそのまま保持されます。最新の請求書は未処理のままになり、請求書は引き続き生成されますが、支払いの試行は行われません。サブスクリプションが `unpaid` の場合は、`past_due` の時点で支払いの試行と再試行がすでに行われているため、プロダクトへのアクセスを取り消します。サブスクリプションのステータスを `active` にするには、期日前に最新の請求書を支払う必要があります。
`paused`	デフォルトの決済手段が設定されずにサブスクリプションのトライアル期間が終了し、trial_settings.end_behavior.missing_payment_method が `pause` に設定されています。サブスクリプションの請求書は今後作成されなくなります。デフォルトの決済手段を顧客に関連付けた後、サブスクリプションを再開できます。

Webhook エンドポイントとインボイス

Webhook エンドポイントを登録して、請求書のステータスを追跡します。請求書を正しく確定できるかどうかの問題はサブスクリプションシステムにとって重要であり、確定に失敗した場合でも適切に処理しなければなりません。

自動回収を有効にすると、Stripe は自動的にインボイスを確定し、自動回収を開始します。

Stripe が invoice.created の成功応答を受信できない場合、自動回収の設定された請求書の確定が最大 72 時間延期されます。ただし、カスタムの確定日を設定している請求書はこの限りではありません。
invoice.created に正しく応答すると、アカウントに設定されたすべての Webhook エンドポイントだけでなく、連結されたあらゆるプラットフォームの Webhook エンドポイントも処理されます。これには、Organizations で設定された Webhook エンドポイントは含まれません。組織で invoice.created をリッスンすることはできますが、自動回収を使用している場合、正しく応答しても請求書の確定に影響を与えることはありません。
同期的に決済を試行するようにサブスクリプションを更新した (初回の請求書で、および一部の更新で) 場合には、このような遅延は発生しません。
請求書を確定しない限り、請求書の支払いは回収できません。Webhook エンドポイントで invoice.finalization_failed イベントをリッスンできることを確認してください。

請求書のイベントタイプの一覧をご覧ください。

イベント	説明
`invoice.created`	インボイスは正常に作成され、確定の準備が整っています。請求書の確定についての詳細は、ドキュメントをご確認ください。 Finalize an Invoice (請求書の確定) API にリクエストを送信することで通知に応答します。
`invoice.finalized`	請求書は正常に確定され、支払いの準備が整っています。顧客にインボイスを送信できます。請求書の確定についてご確認ください。設定に応じて、Stripe は自動的にデフォルトの決済手段に請求するか、収集を試みます。確定後のメールについてご確認ください。
`invoice.finalization_failed`	インボイスを確定できませんでした。ガイドを参照して、請求書の確定の失敗を処理する方法をご確認ください。請求書の概要ガイドに記載されている請求書の確定を確認してください。 Invoice の last_finalization_error を調べて、エラーの原因を判別します。 Stripe Tax を使用している場合、Invoice オブジェクトの automatic_tax フィールドを確認します。 `automatic_tax[status]=requires_location_inputs` の場合、インボイスを確定させることはできず、支払いを回収できません。顧客に通知し、必要な顧客の場所を収集します。 `automatic_tax[status]=failed` の場合、後でリクエストを再試行します。

成功した請求書の確定

Stripe は invoice.created イベントへの成功応答を受信してから 1 時間待機し、その後に決済を試みます。 72 時間以内に成功応答を受信できない場合には、Stripe は請求書の確定と送信を試みます。

1 回限りの請求書をサブスクリプションの請求書とは異なる方法で処理する場合、Webhook 本文の subscription プロパティを確認してください。このプロパティーは、請求書がサブスクリプション用として作成されたかどうかを示します。

本番環境では、Webhook エンドポイントが正しく応答しない場合、Stripe は指数バックオフを使用して最長 3 日間 Webhook 通知の再試行を続けます。サンドボックスでは、数時間にわたって 3 回再試行します。その間は、正常な応答を受信しない限り顧客への請求を試行しません。また、Webhook にエラーが発生していることを知らせるメールも送信します。

この動作は、お客様のアカウントで定義されたすべての Webhook エンドポイントに適用されます。Connect アプリケーション、またはその他のサードパーティーサービスで受信 Webhook を処理できない場合も含まれます。

請求書確定の失敗

Stripe でインボイスを確定できない場合、invoice.finalization_failed イベントが Webhook エンドポイントに送信されます。インボイスを確定できない場合、サブスクリプションは引き続きアクティブなままです。そのため、支払いの回収ができなくても、ユーザーはまだ商品にアクセスできる可能性があります。確定できないインボイスは確実に処理してください。確定されていないインボイスに対して支払いを回収することはできません。

請求書の確定が失敗した理由を判別するには、インボイスオブジェクトの last_finalization_error フィールドを確認してください。ここには、処理を進める方法を含む、失敗に関する詳細な情報が示されています。

Stripe Tax を使用している場合は、automatic_tax.status フィールドが requires_location_inputs になっていないか確認してください。これは、住所情報が無効または不十分であることを示します。認識済みの顧客の所在地が Stripe Tax で見つからない場合、請求書を確定することはできません。請求書の確定失敗を処理する方法をご紹介します。

テスト

Webhook エンドポイントまたはイベントの送信先をテストするには、次の 2 つのオプションのいずれかを選択します。

サンドボックスでアクションを実行し、イベントの送信先に正規のイベントを送信します。たとえば、charge.succeeded イベントをトリガーするには、支払いを成功させるテストカードを使用できます。
Stripe CLI を使用してイベントをトリガーするか、Stripe for Visual Studio Code を使用してイベントをトリガーします。

注