# イベントをリッスンする

インストール済みのユーザーのアカウントでイベントをリッスンする

アプリでは [Webhook](https://docs.stripe.com/webhooks.md) を使用して、ユーザーのアカウントで発生しているイベントに関するアラートを受け取ることができます。これは、アプリで何らかの変更があった場合に、アプリの情報を同期したり、アプリ内でアクションをトリガーしたりするのに役立ちます。

## 始める

1. [アプリのバックエンドで Webhook イベントを処理](https://docs.stripe.com/webhooks.md#webhook-endpoint-def)します。
1. Stripe ダッシュボードで [Webhook エンドポイントを登録](https://docs.stripe.com/webhooks.md#webhooks-summary)し、**連結アカウントでイベントをリッスンする**を選択します。
1. (Recommended) Stripe ダッシュボードでテスト Webhook エンドポイントを登録します。アプリを本番モード、[テストモード](https://docs.stripe.com/stripe-apps/build-backend.md#event-behavior-depends-on-install-mode)、または *サンドボックス* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes)にインストールできます。テストイベントを処理するテストエンドポイントを設定することをお勧めします。
1. 必要な権限ごとに `stripe apps grant permission` を実行して、アプリに必要な権限を追加します。
   ```bash
   stripe apps grant permission "PERMISSION_NAME" "EXPLANATION"
   ```
以下を置き換えます。
   - `PERMISSION_NAME` には権限名が表示されます。
   - `EXPLANATION` には、アクセス有効化についての説明が表示されます。この説明は、アプリのインストール時にユーザーに表示されます。

`event_read` 権限と、処理する特定のイベントに関連付けられた権限を追加する必要があります。特定のイベントにどの権限が必要かについての情報は、[イベントの権限](https://docs.stripe.com/stripe-apps/reference/permissions.md#event-permissions)]でご確認ください。

たとえば、`payment_intent.succeeded` イベントと `setup_intent.succeeded` イベントを処理する場合は、次のコマンドを実行します。

```bash
stripe apps grant permission "event_read" "Read webhook event data"
stripe apps grant permission "checkout_session_read" "Read Checkout Session data in webhook events"
stripe apps grant permission "payment_intent_read" "Read PaymentIntent data in webhook events"
stripe apps grant permission "setup_intent_read" "Read SetupIntent data in webhook events"
```

これらのコマンドを実行した後のアプリのマニフェストファイルは次のようになります。

```json
{
  "id": "com.example.app",
  "version": "1.2.3",
  "name": "Example App",
  "icon": "./example_icon_32.png","permissions": [
    {
      "permission": "event_read",
      "purpose": "Read webhook event data"
    },
    {
      "permission": "checkout_session_read",
      "purpose": "Read Checkout Session data in webhook events"
    },
    {
      "permission": "payment_intent_read",
      "purpose": "Read PaymentIntent data in webhook events"
    },
    {
      "permission": "setup_intent_read",
      "purpose": "Read SetupIntent data in webhook events"
    }
  ]
}
```

## アカウントでイベントをリッスンする

アカウントのユーザーのみに提供されている非公開アプリのイベントを受け取るには、以下のようにします。

1. アプリのバックエンドで [Webhook イベント](https://docs.stripe.com/webhooks.md#webhook-endpoint-def)を処理します。
1. Stripe ダッシュボードで [Webhook エンドポイントを登録](https://docs.stripe.com/webhooks.md#webhooks-summary)します。

## アプリに関するイベント通知を受け取る

*Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) を使用して Stripe アプリのイベント (ユーザーによるインストールやアンインストールなど) をリッスンし、次のリアクションをシステムのバックエンドで自動的にトリガーできるようにします。

- ユーザーアカウントの作成
- 権限の更新
- ユーザーアカウントの無効化およびデータの削除

Stripe Apps では、[Stripe がサポートするイベントタイプ](https://docs.stripe.com/api/events/types.md)に加えて次のイベントもサポートされます。

| 加盟店のアクション             | 結果としてアプリのバックエンドに送信される Webhook イベント                                                                                           |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| アプリを接続またはインストールする     | [account.application.authorized](https://docs.stripe.com/api/events/types.md#event_types-account.application.authorized)     |
| アプリを接続解除またはアンインストールする | [account.application.deauthorized](https://docs.stripe.com/api/events/types.md#event_types-account.application.deauthorized) |

## Webhook をローカルでテストする

次を対象に、Webhook をローカルでテストできます。

- 貴社のアカウントのすべてのユーザーのみが入手でき、自身のアカウントのイベントをリッスンするアプリ
- Stripe App Marketplace で入手でき、貴社のアプリをインストールしたアカウントのイベントをリッスンするアプリ

Webhook をローカルでテストするには次のようにします。

1. [Stripe CLI をインストール](https://docs.stripe.com/stripe-cli.md)します。

1. 次のようにアカウントを認証します。

   ```bash
   stripe login
   ```

1. 端末ウィンドウを 2 つ開きます。

   - ある端末ウィンドウで、[イベント転送を設定](https://docs.stripe.com/webhooks.md#local-listener)します。

     #### App Marketplace での公開

     ```bash
     stripe listen --forward-connect-to localhost:{{PORT}}/webhook
     ```

     #### 貴社のアカウントのみの非公開アプリ

     ```bash
       stripe listen --forward-to localhost:{{PORT}}/webhook
     ```

   - 別の端末ウィンドウで、[イベントをトリガーして Webhook との連携をテスト](https://docs.stripe.com/webhooks.md#trigger-test-events)します。

     #### App Marketplace での公開

     ```bash
     stripe trigger --stripe-account {{EVENT_NAME}}
     ```

     #### 貴社のアカウントのみの非公開アプリ

     ```bash
       stripe trigger {{EVENT_NAME}}
     ```

詳細については、[Webhook エンドポイントのテスト](https://docs.stripe.com/webhooks.md#local-listener)に関する Stripe ドキュメントをご覧ください。

## See also

- [サーバー側のロジック](https://docs.stripe.com/stripe-apps/build-backend.md)
- [権限リファレンス](https://docs.stripe.com/stripe-apps/reference/permissions.md)
- [API 認証タイプ](https://docs.stripe.com/stripe-apps/api-authentication.md)
- [イベントの送信先](https://docs.stripe.com/event-destinations.md)
- [Webhook](https://docs.stripe.com/webhooks.md)