複数の決済手法をサポートすると、「どのタイミングで顧客が支払いを完了したか」を把握することが難しくなります。
その場で決済が完了するケースの多いクレジットカードやApple / Google Payに対し、銀行振込やコンビニ決済などでは入金が完了するまで数日かかるケースも存在します。
決済以外にも、サブスクリプションの契約更新やカード情報の有効期限切れ、トライアルの終了など様々なイベントがオンライン決済では発生します。
入金タイミングやサブスクリプションに関するイベントを、Webhookイベントとして一本化する
Stripeを利用する場合、このような決済に関するイベントを、Webhookイベントとして処理することをお勧めしています。
「決済方法ごとにステータスを確認するシステムを用意する」のではなく、「決済が完了したことを、Webhookイベントで受信したら処理を行う」形にすることで、様々な場面・決済方法をサポートできます。
Amazon EventBridgeを利用した、Webhookイベント受信システムの簡単セットアップ
Webhookイベントの受信方法・処理方法にはいくつかの方法があります。
今回は、2022/08にAWSがリリースしたAmazon EventBridgeとの連携について紹介します。
Step1: Stripeダッシュボードで、Webhook API用の署名シークレットを取得する
EventBridgeのStripe連携では、AWS CloudFormationを利用して必要なリソースをAWS上にデプロイします。
その際に設定パラメータとしてWebhook用の署名シークレットを入力する必要があるため、前もって取得しておきましょう。
Stripeダッシュボードにアクセスし、[開発者 > Webhook]を開きましょう。
https://dashboard.stripe.com/test/webhooks
[エンドポイントを追加]をクリックし、新規登録画面を開きます。
ここでは、署名シークレットの取得だけが目的ですので、一旦[エンドポイントURL]にダミーのURLhttps://example.comを入力します。
[リッスンするイベントの選択]の[イベントを選択]をクリックし、[全イベントを選択]をクリックします。
[イベントを追加]ボタンをクリックすると、Webhookの設定詳細ページに移動します。
[署名シークレット]下にある[表示]をクリックすると、whsec_から始まる署名シークレットが表示されます。
この値をコピーして、次のステップに進みます。
Step2: Amazon EventBridge クイックスタートからStripe連携をセットアップする
続いてWebhookイベントをEventBridgeに送るためのAPIなどを作成します。
AWSマネージメントコンソールの[Amazon EventBridge]に移動し、 [デベロッパーリソース]の[クイックスタート]を開きましょう。
Stripeと連携できるリソースは、[Lambda fURL を使用したインバウンドウェブフック]からセットアップしますので、[使用を開始する]リンクをクリックしましょう。
現在利用できるテンプレートの候補が表示されます。ここから[Stripe]を探して、[設定]をクリックしましょう。
設定方法のウィザードが立ち上がります。
イベントバスを選択する必要がありますが、現在稼働中のバスが特にない様子であれば、defaultのままで問題ありません。
続けて[ステップ２]の[新しいStripeウェブフック]ボタンをクリックしましょう。
URLに関する注意事項が表示されますので、チェックボックスをオンにして[確認]をクリックします。
クリックすると、CloudFormationの立ち上げ画面が起動します。
StripeWebhookSecretに前のステップでコピーしたwhsec_から始まる署名シークレットを入力しましょう。
IAMなどのリソースを生成することへのチェックボックスが下部にありますので、全てチェックをつけて、[スタックの作成]をクリックします。
注意点: [スタックの名前]は重複NG
すでに一度同様のステップでCloudFormationスタックを立ち上げている場合、Stack [StripeInboundWebhookStack] already existsエラーが表示されることがあります。
これは[スタックの名前]が重複しているために表示されるエラーですので、[スタックの名前]に数字を足すなどして変更しましょう。
作成に成功すると、CloudFormationの管理画面に移動します。
ステータスがCREATE_COMPLETEに変われば、作成完了です。
[出力]タブをクリックし、FunctionUrlEndpointのURLをコピーしましょう。このURLがStripeが呼び出すWebhookのエンドポイントとなります。
Step3: Stripeダッシュボードで、WebhookのURLを変更する
URLのコピーができれば、Stripeダッシュボードに戻ります。
先ほど作成したWebhookの設定詳細画面に移動し、右上の[...]ボタンから[詳細情報の更新]をクリックしましょう。
[エンドポイントURL]を入力する欄に、先ほどコピーしたURLを設定して、[エンドポイントを更新]をクリックします。
これでStripe上で起きたイベントを、AWS Lambda経由でAmazon EvenrBridgeに送信できるようになりました。
Step4: Amazon EventBridgeでStripeのイベントを受け付けるルールを作成する
次のステップでは、Amazon EventBridgeに送られてきたイベントから、特定の処理を実行するためのルールを作ります。
再びAWSのマネージメントコンソールに戻り、Amazon EventBridgeのページに移動しましょう。
[イベント]の[ルール]を選択し、[ルールを作成]ボタンをクリックします。
ルール作成ウィザードが立ち上がります。
ルールの基本設定を行う
まず[名前]と[イベントバス]そして[ルールタイプ]を指定します。
[イベントバス]は、Step2でリソースを作成した時に指定したバスと同じもの（変更していなければ、default）を指定しましょう。
また、[ルールタイプ]では[イベントパターンを持つルール]を指定します。
[次へ]をクリックすると、イベントパターンの設定画面に移ります。
受け付けるイベントの種類・パターンを設定する
次の設定画面では、どのイベントを受け付けるルールにするかを設定します。
はじめにイベントのソースを指定する必要があります。
Stripeの場合、[AWS イベントまたは EventBridge パートナーイベント]を選びましょう。
ページを下にスクロールすると、[サンプルイベント - オプション]が表示されます。
これはオプションですが、この後設定する「イベントパターン]のテストに利用できますので、選択だけしておきましょう。
[EventBridgeパートナーイベント]を選択し、[サンプルイベント]から[charge.succeeded]を選びます。
さらにスクロールして、[イベントパターン]の設定を行います。
Stripeの場合、[イベントソース]を[EventBridgeパートナー]設定し、[パートナー]で[Stripe]を選択しましょう。
[イベントタイプ]を[すべてのイベント]にすると、Stripeから送られてきたイベント全てが対象になります。
もし絞り込みをしたい場合は、該当するイベントをセレクトボックスから選ぶか、[カスタムパターン（JSONエディタ）]を利用して個別に指定しましょう。 JSONエディタで指定するJSONのサンプルは、本記事の最後の方で紹介します。
イベントパターンの設定が終われば、[テストパターン]ボタンをクリックしてルールのテストができます。
上の段で指定したサンプルイベントと、設定したイベントパターンが一致すれば成功メッセージが表示されます。
[次へ]をクリックすると、ルールに該当した時に実行する処理を選択する画面に移動します。
Step5: ルールに応じてAWS上で実行する設定を行う
[ターゲットを選択]では、イベントパターン・ルールに一致した場合に呼び出すAPI・リソースの指定ができます。
AWS LambdaやStep Functionsを指定することで、任意のコードを実行することができます。
動きの確認・デバッグが目的の場合は、[CloudWatch ロググループ]を選択しましょう。
送られてきたデータを記録するためのロググループ名の入力が求められますので、stripe-webhookなど「Stripeからのデータであること」がわかるグループ名を設定しましょう。
設定が終わると、リソースの識別に使用するタグの設定画面を経て確認画面に移動します。
ルールの作成が完了すれば、EventBridgeのルール一覧画面に移動し、先ほど作成したルールが一覧に追加されています。
Step6: Stripeドキュメントサイト（Stripe Shell）を使った簡単テスト・デバッグ
特定のイベントを手動で発火させたい場合、Stripe CLIを利用すると簡単です。
Stripe CLIは簡単な用途であれば、ブラウザからも利用できます。
Stripeダッシュボードにログインした状態で、Stripeのドキュメントサイトにアクセスしましょう。
ページ右下にある、上向き矢印のついたアイコンをクリックすると、Stripe CLIを実行するための画面（Stripe Shell）が起動します。
ここでstripe triggerと入力しましょう。するとCLIから実行できるイベントの候補が表示されます。
コマンドを実行すると、そのイベントを発火させるために必要な処理をCLIが自動で実行します。
EventBridgeでの実行に成功しているかは、AWSマネージメントコンソールのルール詳細ページにある[モニタリング]から確認できます。
TriggeredRulesの数値が０のままの場合や、FailedInvocationsの数値が増えている場合は、ルールやトリガーの設定を確認する必要があります。
イベントの中身を確認したい場合は、[CloudWatch ロググループ]をトリガーに追加して、CloudWatch Logsの[ロググループ]からログを確認しましょう。
なお、detailのフィルターを設定している場合はフィルター条件に一致するイベントを発火できないことがあります。もしその場合は、ダッシュボードからの手動操作やAPI呼び出しによるテストをお試しください。
EventBridge運用Tips
サブスクや決済など、特定のイベントのみで実行できるようにする
EventBridgeでは、ルールのフィルターを設定することで、特定のイベントのみ処理するルールを作れます。
例えば以下の画像では、「請求書の支払いが完了した場合」のみ処理を実行させることができます。
{
"source": [{
"prefix": "stripe.com"
}],
"detail-type": ["invoice.paid"]
}
detail-typeでは、「XXから始まるイベント」のような条件も設定できます。そのため、以下のように書くことで、「請求書に関する処理全てのみ」を受け付けることも可能です。
{
"source": [{
"prefix": "stripe.com"
}],
"detail-type": [{
"prefix": "invoice"
}]
}
さらに複数のデータを登録することもできます。
ですので、「顧客データの作成・更新時のみ」のようなルールも指定できます。
{
"source": [{
"prefix": "stripe.com"
}],
"detail-type": ["customer.created", "customer.updated"]
}
金額や契約期間など、特定の条件でのみ実行できるルールを作る
また、EventBridgeではdetailを利用してより詳細なフィルタールールも設定できます。
detailの中にはStripeが送信するWebhookイベントのJSONが含まれています。
{
"version": "0",
"id": "123-456-789",
"detail-type": "invoice.updated",
"source": "stripe.com",
"account": "0123456789",
"time": "2022-09-07T06:23:31Z",
"region": "us-east-1",
"resources": [],
"detail": {
"id": "evt_xxxxxxxxxxx",
"object": "event",
"api_version": "2020-08-27",
"created": 1662531810,
"data": {
"object": {
"id": "in_xxxxxxxxxx",
"object": "invoice",
"account_country": "JP",
"account_name": "テストアカウント",
このデータに対応する形で条件を定義しましょう。
以下の例では、「（割引・課税後の）合計金額が5,000円を超える請求書」のみを受け付けます。
{
"source": [{
"prefix": "stripe.com"
}],
"detail-type": [{
"prefix": "invoice"
}],
"detail": {
"data": {
"object": {
"total": [{
"numeric": [">", 5000]
}]
}
}
}
}
フィルタリングのルールについては、AWSのドキュメントを参考にお試しください。
AWSのコストやスロットリングを回避するため、送信するイベントを限定する
今回紹介した方法では、EventBridgeにイベントを送信する際に、AWS Lambdaを利用します。
そのためEventBridgeで利用する予定のないイベントは、StripeダッシュボードのWebhook設定で送信対象から外すことをお勧めします。
必要のないイベントの送信を停止することで、Lambdaの利用料金を節約することができます。
また、問題が発生した際の調査をしやすくなることや、大量のイベントが送信されることでスロットリングされる恐れを回避することなども期待できます。
どのようなイベントが、いつStripeから送信されているかを確認したい場合は、Stripe CLIまたはStripe Shellでstripe listenコマンドを実行してみましょう。
おわりに: StripeとAWSを利用した「イベント駆動」なサービス開発をはじめよう
デプロイされたLambdaのコードを確認すると、Stripeから送られるWebhookイベントの検証や処理・エラーハンドルなどが実装されていることがうかがえます。ちなみにランタイムはPythonでした。
これらのハンドリングを自前で実装・運用するコストと比較すると、AWSでサービスを構築している場合には非常に便利なツールではないかと思います。
さまざまな決済方法や契約パターンに対応できるシステムを作るため、Stripe WebhookとEventBridgeを利用したイベント駆動なサービス開発を、ぜひお試しください。
ドキュメント
[PR] Stripe開発者向け情報をQiitaにて配信中！
- [Stripe Updates]：開発者向けStripeアップデート紹介・解説
- ユースケース別のStripe製品や実装サンプルの紹介
- Stripeと外部サービス・OSSとの連携方法やTipsの紹介
- 初心者向けのチュートリアル(予定)
など、Stripeを利用してオンラインビジネスを始める方法について週に２〜３本ペースで更新中です。