今日は、Stripe の Webhook のハンドリングを Azure 環境で実際に組み立ててみたいと思います。

• Azure上でStripe の Webhook を活用したアプリを構築したい
• Webhook のハンドリングのベストプラクティスを知りたい
• さくっと動作確認できる環境を作りたい

なお長くなるのでこの記事は前編になります。

【Stripe】Webhookの実装をAzure環境に構築する【後編】

はじめに

要件

• Stripe 上に Customer を作成できる API を実装する
  • 受け付けるパラメータとしては、「名前」,「メールアドレス」とする
  • 顧客作成時にサブスクリプションの契約は不要とする
• 顧客作成が完了したタイミングで、BlobStorage に顧客情報を保存する
  • 保存する情報は「CustomerId」,「名前」,「メールアドレス」,「作成日時」とする
  • {CustomerId}.json」をファイル名とする json 形式で保存する

Azure システムアーキテクチャ

1. クライアントが WebApps にて実装した API に対して Customer 作成の要求を出します。
2. API が Stripe の CreateCustomerAPI を実行し、Stripe 上に Customer を作成します。
3. Stripe 上で Customer が作成されたタイミングで、customer.created の Webhook イベントがされます。
4. イベントを受けた WebApps は ServiceBus の Queue に対して Enqueue します。
5. Enqueue からのメッセージをトリガーとして、Functions が実行されます。
6. Functions が StorageAccount に対してファイルを保存します。

リソース準備

dotnet new webapi -n StripeWebhookApp

Azure ServiceBus

dotnet add package Stripe.net --version 42.4.0

using Microsoft.AspNetCore.Mvc;
using Stripe;

namespace StripeWebhookApp.Controllers;

[ApiController]
public class StripeCustomerController : ControllerBase
{
    private readonly ILogger<StripeCustomerController> _logger;

    public StripeCustomerController(ILogger<StripeCustomerController> logger)
    {
        _logger = logger;
    }

    [HttpPost("api/customers")]
    public async Task<StripeCustomerModel> Create(StripeCustomerModel req)
    {
        //今回は実装の簡略化のため、APIキーをハードコードしていますが
        //セキュアな情報であるため実際に実装するためにはKeyVaultなどに保管し
        //アプリから参照するようにしてください。
        StripeConfiguration.ApiKey = "sk_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";

        var options = new CustomerCreateOptions
        {
            Name = req.Name,
            Email = req.EMailAddress
        };
        var service = new CustomerService();
        Customer createdCustomer = await service.CreateAsync(options);

        StripeCustomerModel response = new (createdCustomer.Name, createdCustomer.Email);
        return response;
    }
}

namespace StripeWebhookApp;

public class StripeCustomerModel
{
    public StripeCustomerModel(string name, string eMailAddress){
        Name = name;
        EMailAddress = eMailAddress;
    }
    public string Name { get; set; } = string.Empty;
    public string EMailAddress { get; set; } = string.Empty;
}

dotnet run .\StripeWebhookApp.csproj

http://localhost:{port}/swagger

using Azure.Identity;
using Azure.Messaging.ServiceBus;
using Microsoft.AspNetCore.Mvc;
using Stripe;

namespace StripeWebhookApp.Controllers;

[ApiController]
public class StripeIncomingWebhookController : ControllerBase
{
    [HttpPost("api/webhooks/incoming")]
    public async Task<ActionResult> IncomingWebhook()
    {
        using (StreamReader reader = new(HttpContext.Request.Body))
        {
            string readEvent = await reader.ReadToEndAsync();

            //自らが想定するStripeのWebhookイベントであることを検証
            //whsec_から始まるシークレットは、StripeのWebhookの設定画面から取得可能
            EventUtility.ValidateSignature(readEvent, Request.Headers["Stripe-Signature"]
            , "whsec_XXXXXXXXXXXXXXXXXXX");

            //ServiceBusへのEnqueue処理
            ServiceBusClient client = new("sbns-stripe-webhook.servicebus.windows.net", new DefaultAzureCredential());
            ServiceBusSender sender = client.CreateSender("sbq-stripewebhook");

            ServiceBusMessage serviceBusMessage = new(readEvent);
            await sender.SendMessageAsync(serviceBusMessage);

            return Ok();
        }
    }
}

whsec_から始まるキーに関しては、後ほど行う Stripe 上の設定で取得できます。

補足：ServiceBusClientについて

また、今回は記事の対象外としていますが、ServiceBusClient の扱いに関しても本来注意が必要です。
現段階だと API がコールされるたびに Client を生成していますが、これは本来避けるべきです。
そのあたりの内容に関してはこちらにも書いていますので、興味がある方はご覧ください。

エンドポイントURLは、WebAppsのエンドポイントを指定しましょう。

バージョンに関しては、WebhookをハンドリングするアプリのSDKのバージョンに合わせます。
今回はversion 42.4.0のものを利用しているため、2023-08-16としました。

リッスンするイベントの選択は、必要最低限のイベントのみ受信することが推奨されているため、今回は customer.created のみ設定します。

作成が完了したら、署名シークレットが発行されるので、先ほどの API の実装で利用します。

繰り返しになりますが、こちら実際に実装する際はハードコードを避けましょう。

動かしてみる

ではここまで作れたら実際に動かしてみましょう。

先程作成していたアプリケーションを WebApps にデプロイします。

その後、デプロイした API を利用して Customer を作成します。

postman 等で CreateCustomer の API を実行しましょう。

そうすると、最初に述べた 1.~4.まですべて完了しているはずです。

順を追って確認します

動作確認

StripeDashboard上で、新規に Customer が作成されていることが確認できます。
このCustomerを追っていきたいと思うので、CustomerIDを控えておきます。

cus_OcIKnZS8cVAzNC

では、この作成によって発行されたStripeのEventを確認します。

StripeDashboardの開発者タブから、先ほど作成したWebhookのエンドポイントを作成します。

そうすると、1件「customer.created」のイベントが追加されている事が確認できます。
また、イベント内容を見ると先ほどのCustomerIdが記載されていることも分かります。

ではこのイベントがキューに追加されているか確認してみましょう。
作成したServiceBusのQueueからメッセージを確認します。

すると、Queueに1件メッセージがためられていることが確認できます。
また、内容を見ると先ほどのEventIdとCustomerIdが紐づいていることも確認できますね。

これで

1. クライアントが WebApps にて実装した API に対して Customer 作成の要求を出します。
2. API が Stripe の CreateCustomerAPI を実行し、Stripe 上に Customer を作成します。
3. Stripe 上で Customer が作成されたタイミングで、customer.created の Webhook イベントがされます。
4. イベントを受けた WebApps は ServiceBus の Queue に対して Enqueue します。

の流れが実装できたことが確認できました。

なぜキューを経由するのか？

最初にも少し触れましたが、なぜわざわざキューを経由するのでしょうか。
今回であれば、IncomingWebhookのAPIでイベントを受けたタイミングで、StorageAccountへ追加すればよいのではないでしょうか？

これに関しては色々と理由があります。

時間制限

イベントを受けてから20秒以内に2xxのレスポンスを返さない場合、Stripe側で失敗とみなされます。
そのため重たい処理を実行するのは推奨されず、出来るだけ早くレスポンスを返す必要があります。

Stripeのドキュメントにも以下のような記載があります。

エンドポイントは、タイムアウトを発生させかねない複雑なロジックの前に、素早く成功のステータスコード (2xx) を返す必要があります。たとえば、会計システムで顧客の請求書を支払い済みとして更新する前に、200 のレスポンスを返す必要があります。

リトライ処理

例えば、Webhookのイベント自体は正常に受け取れたが、StorageAccountへの保存に失敗した場合にStripe側に4xxを返すとします。
そうした場合、Stripe側ではリトライ送信が行われます。

ただ、このリトライ送信の間隔などはStripe側の実装に依存し、ドキュメントには

本番環境では、Stripe は指数バックオフを使用して最長 3 日間、お客様の Ｗebhook エンドポイントに対する特定のイベントの配信を試行します。ダッシュボードのイベントセクションで、次回の再試行が発生する時期を確認できます。

と記載があります。

アプリとしてのリトライ処理の要求を、このStripeのリトライ送信の間隔に基づいて実装するのはやや危険ですよね。
それよりは、自分で用意したキューのリトライ設定を正しく設計するべきです。

そのため、IncomingWebhookのAPIに関しては

1. イベントの受信・検証
2. キューへの追加
3. エンドポイントへのレスポンス

のみに集中し、その後の処理に関してはStripeWebhookから独立した場所で処理を行うべきだと考えます。

まとめ

今回はStripeのWebhookハンドリングをAzure環境で実装してみる、と題してキューに追加するところまで実装しました。
Webhookのイベントの扱いに関しては色々と注意する点があります。
ドキュメントには今回触れた部分以外にも、色々と記載があるので是非ご一読ください。

では後編で会いましょう！