Stripe と Squid の Webhooks

Squid の `@webhook` デコレータを使用して Stripe のイベントに応答

Webhook は、イベント発生時にアプリまたはサービスから送信される HTTP リクエストです。リクエストのペイロードには、イベントに関する有用な情報が含まれており、それを用いて自身のコード内でアクションを実行できます。通常、HTTP エンドポイントは製品のダッシュボードを通じてサービスに提供されます。各製品には固有のイベントがあり、それぞれに webhook を設定できますが、以下はよくあるシナリオの例です:

新規ユーザーの作成
ユーザープロフィールの更新
データベースやストレージの変更
Analytics events

このチュートリアルでは、Stripe の顧客の請求書ステータスが 'paid' に変わったときに実行される webhook を作成します。

作成するもの

Stripe webhooks に応答して、組み込みデータベースにデータを追加する Squid バックエンド

学べる内容

Stripe イベントにフックする Squid Service の作成方法
データベースにセキュリティ機能を追加する Squid Service の作成方法

必要なもの

The Squid CLI
A Squid account
A Stripe account
The Stripe CLI
Optional: An Auth0 account with a single-page application configured to use React

環境のセットアップ

次のコマンドを使用して Squid CLI をインストールします:
```
npm install -g @squidcloud/cli
```
notes-app のコードサンプルをダウンロードします:
```
squid init-sample stripe-webhooks --template stripe-webhooks
```
お好みの IDE でプロジェクトを開きます.

starter プロジェクトには frontend と backend の2つのフォルダがあることに注意してください。今回記述するコードはバックエンド側のみのため、現時点ではフロントエンドに変更を加える必要はありません。最後に、リアルタイムでドキュメントの更新を確認できるようにフロントエンドを設定するオプションがあります。

Squid バックエンドのセットアップ

There are two subfolders that make up the stripe-webhooks project: frontend and backend. The backend folder contains the Squid backend for the app.

Navigate to the Squid Console and create a new application named stripe-webhooks.

In the Squid Console, navigate to the application overview page and scroll to the Backend project section. Click Create .env file and copy the command.

Copy Env Command

In the terminal, change to the backend directory:

cd backend

Create the .env file using the command you copied from the console. The command has the following format:

squid init-env --appId YOUR_APP_ID --apiKey YOUR_API_KEY --environmentId dev --squidDeveloperId YOUR_SQUID_DEVELOPER_KEY --region us-east-1.aws

Install the required dependencies:

npm install

The backend is now set up and ready to use with a frontend!

Webhook サービスの作成

このセクションで作成する webhook Squid Service は、新しい請求書とそのステータスの追加、または既存の請求書のステータスを 'paid' に更新するためのものです。各フィールドのキーは Stripe の請求書 ID であり、値は 'paid' または 'unpaid' です。

ドキュメント ID はユーザーの認証 ID です。セキュリティルールにより、ユーザーは自分自身の請求書のみを閲覧できるように設定されています。構造を視覚化すると、次のようになります:

userPayments:
  squidUserId123: {
    kaglautA235980A: 'paid'
    Edg26GH697dk104: 'unpaid'
    ...
  squidUserId456: {
    SFHGhg995gja0435: 'unpaid'
    ...

backend/src/service/ に移動し、stripe-webhook-service.ts ファイルを開きます。

StripeWebhookService クラス内に、以下の関数を追加します:

backend/src/service/stripe-webhook-service.ts
async addInvoiceToDatabase(stripeUserId: string, invoiceId: string, paid: boolean): Promise<string | any> {
    const paidStatus = paid ? 'paid' : 'unpaid';

    try {
      // Find user in database
      const userDocs = await this.squid.collection('userPayments').query().eq('stripeUserId', stripeUserId).snapshot();

      if (userDocs.length === 0) {
        console.log('new user found, adding to database');
        const newInvoices = { [invoiceId]: paidStatus };
        await this.squid
          .collection('userPayments')
          .doc('squidUserId123')
          .insert({ stripeUserId: stripeUserId, invoices: newInvoices });
        return 'new user, database update complete';
      }

      const newInvoices = { ...userDocs[0].data.invoices, [invoiceId]: paidStatus };
      await userDocs[0].update({ invoices: newInvoices });
      return 'database update complete';
    } catch (error) {
      console.error(error);
      return error.message;
    }
}

このヘルパー関数は、Stripe のカスタマー ID、Stripe の請求書 ID、および請求書の 'paid' ステータスという3つのパラメータを受け取ります。指定された Stripe カスタマー ID を持つユーザーのドキュメントを userPayments コレクションから問い合わせ、そのユーザーの請求書に新しい請求書を追加します。

ドキュメントが見つからない場合、squidUserId123 をキーとする新しいドキュメントが追加されます。これは、すべての Stripe カスタマーには関連する Squid ユーザー ID が存在し、したがってそのユーザー ID をキーとするドキュメントがあるべきという前提のデモンストレーションです。実際のアプリケーションでは、このシナリオを別の場所にエラーログとして記録する可能性があります。

addInvoiceToDatabase 関数の後に、以下のコードを追加します:
backend/src/service/stripe-webhook-service.ts
```
@webhook('handleStripePayment')
  async handleStripePayment(request: WebhookRequest): Promise<WebhookResponse | any> {
    const stripeUserId = request.body.data.object.customer;
    const invoiceId = request.body.data.object.id;
    const response = await this.addInvoiceToDatabase(stripeUserId, invoiceId, true);
    return this.createWebhookResponse(response);
  }
```
この関数は @webhook デコレータを使用しており、Squid webhook としてマークされています。エンドポイント URL には handleStripePayment という文字列が使用されるため、エンドポイントの目的が明確になるような値を選んでいます。

Stripe から送信されるリクエストの body には customer と id プロパティが含まれており、詳細については Stripe documentation on webhooks を参照してください。

これらの属性は addInvoiceToDatabase 関数に渡され、その後 Squid の createWebhookResponse 関数を使用して Stripe にレスポンスが送信されます。
backend フォルダ内で、次のコマンドを実行してローカルで Squid バックエンドを起動します:
```
squid start
```
端末のログには webhook 用の URL が表示されます。ログは次のように表示されます:
```
| Available webhooks:
| Webhook URL for handleStripePayment: https://YOUR_APP_ID-dev-YOUR_SQUID_DEVELOPER_ID.us-east-1.aws.squid.cloud/webhooks/SQUID_WEBHOOK_NAME
```
この URL は次のセクションで必要になるので、控えておいてください。

Stripe カスタマーの追加

このセクションでは Stripe account が必要です。

テストモードで、Stripe dashboard の Customers セクションに移動します。
Add customer をクリックします。カスタマー名は John Doe またはお好みの名前にしてください。
Add customer をクリックして新規カスタマーを保存します。

Stripe に webhook を追加

Stripe dashboard で Developers をクリックします。
Developers ページで、Wehooks タブをクリックします。
Add endpoint をクリックします。
端末ログからエンドポイント URL を貼り付けます。念のため、Endpoint URL は次の形式になっています:
```
https://YOUR_APP_ID-dev-YOUR_SQUID_DEVELOPER_ID.us-east-1.aws.squid.cloud/webhooks/handleStripePayment
```

注記

ここで使用している URL の形式は dev 環境用です。prod 環境のエンドポイント形式は https://YOUR_APP_IDYOUR_SQUID_DEVELOPER_ID.APP_REGION.squid.cloud/webhooks/SQUID_WEBHOOK_NAME となります.

Select events をクリックして invoice.paid を選択します。検索バーを使用すると便利です。
Add endpoint をクリックします。

Webhook のテスト

新しいターミナルウィンドウを開きます。現在、2つのターミナルウィンドウが開いているはずです。まだインストールしていない場合は、Stripe CLI をインストールしてください。
Stripe カスタマー ID を保存するための環境変数を追加します。Stripe カスタマー ID は、Stripe の Customers dashboard 内の details セクションで確認できます。
```
export customer=YOUR_STRIPE_CUSTOMER_ID
```
次の Stripe コマンドを使用して、カスタマーの新しい 'paid' 請求書を作成します:
```
stripe trigger invoice.paid --override invoiceitem:customer=$customer --override invoice:customer=$customer --override payment_method:customer=$customer
```
このチュートリアルの目的上、これらのフラグの詳細についてはあまり気にする必要はありません。Stripe CLI の詳細について知りたい場合は、Stripe's reference docs をご覧ください.

注記

このコマンドは、設定した一時的な環境変数を使用しています。他のターミナルウィンドウでこのコマンドを実行する場合は、再度 customer 変数を設定する必要があります.

Stripe dashboard の webhooks タブからエンドポイントを選択します。そこで発生したイベント、Squid のレスポンス、およびリクエストの body を確認できます。
Stripe dashboard で Customers タブを選択し、カスタマーのプロファイル内の Invoices セクションまでスクロールします。'paid' 請求書が追加されていることを確認してください.

また、顧客リストには名前のない新しいカスタマーが追加されます。Stripe CLI を使用して invoice.paid イベントをテストすると新しいユーザーが作成されますが、これはライブイベントでは発生しません。

おめでとうございます！

おめでとうございます！ Stripe でトリガーされたイベントに応答する Squid Service webhook を作成しました。ここで作業を終了しても構いませんが、さらに追加することも可能です。

ボーナスセクション: フロントエンドアプリの追加

バックエンド上で更新されたドキュメントデータを表示するために、クエリを追加してドキュメントを取得し、その結果をログに記録することもできます。しかし、アプリ内でデータをどのように使用するかをよりよく反映するためには、フロントエンド上で更新内容を表示するのが最適です。

以下のボーナス手順では、Stripe イベントに応答してデータベースのリアルタイム更新を表示できるフロントエンドを設定します。

React を使用する single-page application configured to use React を持つ Auth0 account が必要です。

Auth0 統合の追加

まだ Auth0 アプリを作成していない場合は、Auth0 account を設定し、single-page application configured to use React を作成してください。
コールバック URL およびログアウト URL を追加する際には、http://localhost:5173 を使用してください。
dev 環境の Squid Console で Integrations タブを選択します。
Available integrations タブをクリックして、すべての統合を表示します。
Auth0 統合までスクロールし、Add integration をクリックします。
Integration ID に auth0 と入力します。
Auth0 コンソールで確認できる、Auth0 アプリの client ID と domain を入力します。
Add integration をクリックします。

フロントエンドへの Squid の追加

The following steps add configuration parameters to connect the application to Squid.

Open a new terminal window and navigate to the project's frontend. You should now have two open terminal windows: one for the app's backend and one for the frontend.

cd frontend

Install the required dependencies:

npm install

Run the following command to create a .env.local file with the Squid environment configuration needed to initialize Squid:

npm run setup-env

frontend/src/main.tsx に移動します。設定が必要な Auth0Provider コンポーネントがあることに注意してください:

frontend/src/main.tsx
ReactDOM.createRoot(document.getElementById('root') as HTMLElement).render(
  <Auth0Provider
    domain="AUTH0_DOMAIN"
    clientId="AUTH0_CLIENT_ID"
    authorizationParams={{
      redirect_uri: window.location.origin,
      audience: 'auth0-api-id',
    }}
  >
    <SquidContextProvider
      options={{
        appId: import.meta.env.VITE_SQUID_APP_ID,
        region: import.meta.env.VITE_SQUID_REGION,
        environmentId: import.meta.env.VITE_SQUID_ENVIRONMENT_ID,
        squidDeveloperId: import.meta.env.VITE_SQUID_DEVELOPER_ID,
      }}
    >
      <App />
    </SquidContextProvider>
  </Auth0Provider>
);

Auth0Provider コンポーネント内のプレースホルダーを、Auth0 アプリケーションの domain および client ID に置き換えます。
frontend/src/App.tsx ファイルを開き、stripeUserId 変数内のプレースホルダーを、作成したカスタマーの Stripe Customer ID に置き換えます。この ID は Stripe dashboard で確認できます.
frontend/src/App.tsx
```
...
function App() {
  const stripeUserId = '[YOUR_STRIPE_CUSTOMER_ID]'
...
```
frontend フォルダ内で、次のコマンドを実行します:
```
npm run dev
```
フロントエンドアプリを表示するには、ターミナルに表示された PORT に従い、localhost:PORT にアクセスしてください。通常、アドレスは http://localhost:5173 です。
Log in ボタンを使用してログインします。
Add mock data をクリックして、架空の請求書を生成します。
Stripe コマンド用のターミナルウィンドウで、あなたのカスタマーに対して別の 'paid' 請求書を作成します。可能であれば、コマンドを別の画面で実行するか、ターミナルウィンドウを縮小してウェブアプリも同時に閲覧できるようにしてください.
```
stripe trigger invoice.paid --override invoiceitem:customer=$customer --override invoice:customer=$customer --override payment_method:customer=$customer
```
ウェブアプリで新しい 'paid' 請求書が追加されたことを確認してください。素晴らしいです！

おめでとうございます! 🦑

素晴らしいです！ Stripe のイベントに応答する webhook を作成しただけでなく、リアルタイムで変更を確認できるフロントエンドも設定しました。

次のステップ

Squid でエンドポイントを作成したので、試してみる項目は以下の通りです:

Squid にエンドポイントを追加し、他の Stripe イベントに接続してみる
Webhooks を使用する他の製品と Squid エンドポイントを連携させる
Check out the docs を参照して、Squid Backend SDK で利用可能なその他の機能について学ぶ

Squid の @webhook デコレータを使用して Stripe のイベントに応答​

作成するもの​

学べる内容​

必要なもの​

環境のセットアップ​

Squid バックエンドのセットアップ​

Webhook サービスの作成​

Stripe カスタマーの追加​

Stripe に webhook を追加​

Webhook のテスト​

おめでとうございます！​

ボーナスセクション: フロントエンドアプリの追加​

Auth0 統合の追加​

フロントエンドへの Squid の追加​

おめでとうございます! 🦑​

次のステップ​