# イベントとの連携 Stripe から Webhook エンドポイントとクラウドサービスにイベントを送信します。 > API v1リソースの[シンイベント](https://docs.stripe.com/event-destinations.md#thin-events)はプライベートプレビューで利用可能です。これらを使用すると、Webhook設定を変更することなく、統合のアップグレードを効率化できます。以前は、シンイベントはAPI v2リソースのみをサポートしていました。[詳細を確認し、アクセスをリクエストしてください](https://docs.google.com/forms/d/e/1FAIpQLSeEkqzB02afvlklMkqwA6wsBH90eW8gxmc-hBOvqe2N6TRujQ/viewform?usp=dialog)。 Webhook エンドポイント、[Amazon EventBridge](https://docs.stripe.com/event-destinations/eventbridge.md)、[Azure Event Grid](https://docs.stripe.com/event-destinations/eventgrid.md) など、複数のデスティネーションタイプで Stripe からイベントを受信するイベントデスティネーションを設定します。イベントは、次のいずれかで受信できます。 - リソースをポイント・イン・タイムで表示するための自己完結型 [スナップショットイベント](https://docs.stripe.com/event-destinations.md#choosing-event-format) - 軽量 [Thin イベント](https://docs.stripe.com/event-destinations.md#thin-events)、常に最新のデータに基づいて行動することを保証し、導入するアップグレードプロセスを簡素化します ## ユースケース Stripe のシステムを構築する際、自社のアプリが Stripe アカウントからイベントをリアルタイムで受信できるようにすることをお勧めします。こうすることで、バックエンドシステムはアクションへの応答とアクションの実行を適宜行うできます。 イベントの送信先では、Stripe はアカウントからリアルタイムのイベントデータのプッシュを行うことで、次のようなバックエンドアクションを実行できるようにします。 - 顧客が支払いを確認したときにユーザーに通知を送る - 顧客が支払いに対して不審請求を申請したときに、内部の申し立ての調整プロセスを開始する - 継続的なサブスクリプション支払いに成功したときにユーザーにアクセス権を付与する ## 対応している配送先タイプ [Amazon EventBridge](https://docs.stripe.com/event-destinations/eventbridge.md)を使用してAWSアカウントに、[Azure Event Grid](https://docs.stripe.com/event-destinations/eventgrid.md)を使用してAzureサブスクリプションに、または[Webhookエンドポイント](https://docs.stripe.com/webhooks.md)経由でHTTPSエンドポイントにイベントを送信します。 ## イベントの概要 イベントが発生すると、Stripe は新しい `Event` オブジェクトを生成します。1 つの API リクエストで複数のイベントが生成される可能性があります。例えば、顧客に新しいサブスクリプションを作成すると、`customer.subscription.created` と `payment_intent.succeeded` イベントが発生する可能性があります。プログラムで導入する場合は、これらのイベントが発生したときに受信するようにイベント送信先を設定することを推奨します。イベントが構造化され、宛先に配信される方法は、受信するために選択したフォーマットによって異なります。 `Event` オブジェクトには 2 つのバージョンがあります。 - [Thin events (v2)](https://docs.stripe.com/api/v2/events.md): シンイベントは、v2 `Event` オブジェクトと影響を受けるオブジェクトに関する限定的な情報のみを含む軽量な通知を送信します。その後、API コールを使用して完全な `Event` オブジェクトまたは関連リソースを取得できます。シンイベントは API v2 endpoints によって生成されます。[full list of thin events](https://docs.stripe.com/api/v2/core/events/event-types.md) を参照してください。 - [Snapshot events](https://docs.stripe.com/api/events.md): スナップショットイベントは、更新されたリソースの最終的に整合性のあるスナップショットを含む完全な `Event` オブジェクトを含む通知を送信します。このデータは処理時点ですでに古くなっている可能性があるため、API からリソースの最新バージョンを取得することを推奨します。シンイベント通知とは異なり、配信されるスナップショットイベントはバージョン管理されるため、イベント送信先とクライアントの両方でバージョンを管理する必要があります。これらのイベントは API v1 endpoints と API v2 endpoints の両方によって生成されます。該当する場合、変更を示す `previous_attributes` プロパティが含まれます。[full list of snapshot events](https://docs.stripe.com/api/events/types.md) を参照してください。 ### フォーマットの選択 Thin イベントは、以下のような場合に使用します。 - データの完全性は非常に重要であり、アプリケーションは最新の情報に基づいて実行されなければなりません。 - クライアントサイドだけでアップグレードを管理することで、バージョン管理を簡素化したいとお考えでしょう。 - モダンでタイプセーフなアプリケーションを構築しており、SDK の型付けの利点を活用したいと考えています。 スナップショットイベントは、次のような場合に使用します。 - その後の API コールを行わずに、変更された特定のフィールドを監査する必要があります。 - 導入するには、リソース定義のポイント・イン・タイム表示が必要であり、最終的に一貫性のあるデータを使用しても問題ありません。 この表では、シンイベントとスナップショットイベントの大まかな違いを示しています。 | 特性 | スナップショットイベント | シンイベント | | --- | --- | --- | | 作成者 | API v1 と API v2 の両方のリソース状態変更 | API v2 のリソース状態の変更 | | 配信されたペイロード | **Large**: イベントに関連する API オブジェクトのスナップショットが含まれます | **Small**: シンイベント通知にイベント関連の API オブジェクトの ID を含めます | | イベントを処理するための追加データへのアクセス。 | API から最新のオブジェクト定義を取得します。イベントペイロードのオブジェクト定義は、イベントを処理する時点で古くなっている可能性があります。 | API から最新のオブジェクトを取得するか、`v2/events` から [イベント](https://docs.stripe.com/api/v2/events.md) の完全なものを取得します。完全なイベントペイロードは、イベントに関する追加詳細を含むことができます。例えば、`v1.billing.meter.error_report_triggered` イベントのペイロードには、発生したエラーのタイプと頻度に関する情報が含まれます。 | | SDK のタイプ指定 | タイプ未指定 | タイプ指定 | | バージョン管理 | API バージョンによるバージョン管理 | バージョン管理されないため、Webhook エンドポイント設定を変更することなく、システムをアップグレードできます | | イベントを表示する API | [イベント v1 API](https://docs.stripe.com/api/events.md) | [イベント v2 API](https://docs.stripe.com/api/v2/events.md) | [Accounts v2](https://docs.stripe.com/connect/accounts-v2/migrate-integration.md) を使用する場合、スナップショットイベントとシンイベントの両方をリッスンすることがあります。 ### Thin イベント通知ペイロードの例 次の例は、`v2.core.account.updated` のシンイベント通知を示しています。通知ペイロードの `id` プロパティには、関連する `Event` オブジェクトの ID が含まれています。`reason` ハッシュにはイベントをトリガーした要因に関する情報が含まれ、`related_object` ハッシュには ID を含む関連オブジェクトの情報が含まれています。 `data` や `changes` などの追加のイベントプロパティにアクセスするには、`fetchEvent()` メソッドを使用して完全な `Event` オブジェクトを取得します。`fetchRelatedObject()` メソッドを使用して、関連オブジェクトを取得することもできます。 ```json { "id": "evt_test_65UIRNU7G1XbhCfOim416TgmEI4ASQ3jHxXt8RFwXoeVwO", "object": "v2.core.event", "type": "v2.core.account.updated", "livemode": false, "created": "2026-03-09T13:00:28.435Z", "context": null, "reason": { "type": "request", "request": { "id": "req_v2y9y15XqG3Futmjg", "idempotency_key": "ik_TgmEI3jHxXt8RFw4jS7ve2QcAReDQWBjPAkAEUm" } }, "related_object": { "id": "acct_1T93Q4Pmpb34Vto6", "type": "v2.core.account", "url": "/v2/core/accounts/acct_1T93Q4Pmpb34Vto6" } } ``` ### スナップショットイベントのペイロード例 次の `setup_intent.created` スナップショットイベントの例では、イベントが発生したときのオブジェクト定義が含まれています。 ```json { "id": "evt_1NG8Du2eZvKYlo2CUI79vXWy", "object": "event", "api_version": "2019-02-19", "created": 1686089970, "data": { "object": { "id": "seti_1NG8Du2eZvKYlo2C9XMqbR0x", "object": "setup_intent", "application": null, "automatic_payment_methods": null, "cancellation_reason": null, "client_secret": "seti_1NG8Du2eZvKYlo2C9XMqbR0x_secret_O2CdhLwGFh2Aej7bCY7qp8jlIuyR8DJ", "created": 1686089970, "customer": null, "description": null, "flow_directions": null, "last_setup_error": null, "latest_attempt": null, "livemode": false, "mandate": null, "metadata": {}, "next_action": null, "on_behalf_of": null, "payment_method": "pm_1NG8Du2eZvKYlo2CYzzldNr7", "payment_method_options": { "acss_debit": { "currency": "cad", "mandate_options": { "interval_description": "First day of every month", "payment_schedule": "interval", "transaction_type": "personal" }, "verification_method": "automatic" } }, "payment_method_types": [ "acss_debit" ], "single_use_mandate": null, "status": "requires_confirmation", "usage": "off_session" } }, "livemode": false, "pending_webhooks": 0, "request": { "id": null, "idempotency_key": null }, "type": "setup_intent.created" } ``` ## Thin イベントの使用 API から詳細を取得するために、宛先に送信されたイベント通知を使用して、Thin イベントと導入します。 ### イベント通知の処理 初期通知には最小限のデータが含まれます。イベント通知を処理するとき、導入する必要がある情報に応じて、3 つのアプローチのいずれかを選択します。 1. **完全なイベントの取得**: `fetchEvent()` メソッドを使用して、完全な `Event` オブジェクトを取得します。完全なイベント・オブジェクトは、2 種類の追加データを含むことができます。 - `data` ハッシュで利用可能な、イベント自体のコンテキスト情報。例えば、`v1.billing.meter.error_report_triggered` イベントは、このフィールドの検証エラーのタイプとサマリーに関する詳細を含みます。 - `changes` ハッシュで利用可能な、リソース上で変更された属性の以前の値。 以下の表は、最初の通知と比較して、完全な [イベント](https://docs.stripe.com/api/v2/events.md) オブジェクトで利用可能な追加データの詳細を示しています。 | プロパティ名 | イベント通知 | イベント | | --- | --- | --- | | イベントタイプ | ✓ サポート対象 | ✓ サポート対象 | | 関連リソース ID | ✓ サポート対象 | ✓ サポート対象 | | イベント ID | ✓ サポート対象 | ✓ サポート対象 | | 作成時点のタイムスタンプ | ✓ サポート対象 | ✓ サポート対象 | | 理由 | ✓ サポート対象 | ✓ サポート対象 | | 変更点 | ❌ サポート対象外 | ✓ サポート対象 | | データ | ❌ サポート対象外 | ✓ サポート対象 | 1. **関連オブジェクトの最新の状態を取得します**: `fetchRelatedObject()` メソッドを使用して、イベントに関連付けられたオブジェクトの最新バージョンを取得します。例えば、`v1.billing.meter.error_report_triggered event` を受信した場合、`fetchRelatedObject()` は、エラー報告をトリガーしたメーターオブジェクトを取得します。 2. **通知を直ちに処理します**: 通知のイベントタイプとリソース ID がユースケースに十分な場合、追加の API コールを行わずに処理できます。 以下の例では、イベントを取得するための追加の API コールを行うことなく、イベント通知から関連オブジェクトの最新の状態を直接取得する方法を示しています。 #### Java ```java com.stripe.model.v2.core.EventNotification eventNotification = client.parseEventNotification(payload, signatureHeader, endpointSecret); if (eventNotification instanceof V1BillingMeterErrorReportTriggeredEventNotification) { V1BillingMeterErrorReportTriggeredEventNotification notif = (V1BillingMeterErrorReportTriggeredEventNotification) eventNotification; // fetchRelatedObject() makes one network request to fetch the latest version // of the object associated with this event (a Meter, in this case). // No API call to retrieve the full Event is needed. Meter meter = notif.fetchRelatedObject(); } ``` 以下の例では、コンテキスト情報を含む `data` ハッシュや、以前の属性値を含む `changes` ハッシュなど、実装で追加データが必要な場合に完全な Event オブジェクトを取得する方法を示しています。 #### Java ```java com.stripe.model.v2.core.EventNotification eventNotification = client.parseEventNotification(payload, signatureHeader, endpointSecret); if (eventNotification instanceof V1BillingMeterErrorReportTriggeredEventNotification) { V1BillingMeterErrorReportTriggeredEventNotification notif = (V1BillingMeterErrorReportTriggeredEventNotification) eventNotification; // Use fetchEvent() when you need additional data in the Event object, // such as the "data" hash with contextual info or the "changes" hash // with previous attribute values. com.stripe.model.v2.core.Event event = notif.fetchEvent(); if (event instanceof V1BillingMeterErrorReportTriggeredEvent) { V1BillingMeterErrorReportTriggeredEvent typedEvent = (V1BillingMeterErrorReportTriggeredEvent) event; String summary = typedEvent.getData().getDeveloperMessageSummary(); } } ``` ### SDK のタイプ指定 Thin イベントとその通知は SDK で完全に型付けされています。 - **イベント通知**: イベント宛先に配信される初期の軽量ペイロードは、`{EventType}EventNotification` として型付けされます。 - **Event**: `fetchEvent()` を使用して API から完全なイベントを取得した後、結果のオブジェクトは `{EventType}Event` として型付けされます。 ## イベントの権限 ダッシュボードでイベントを表示するには、ユーザーアカウントに [Admin or Developer role](https://docs.stripe.com/get-started/account/teams/roles.md) を割り当てます。API を使用してイベントを取得するには、デフォルトですべてのイベントタイプを表示できる[シークレット API キー](https://docs.stripe.com/keys.md#create-api-secret-key)か、特定のイベントタイプのリソースに対して `Read` アクセスが有効になっている[制限付き API キー](https://docs.stripe.com/keys.md#create-restricted-api-key)を使用します。たとえば、制限付き API キーの `Read` アクセスを `payment_intent` リソースに付与すると、`payment_intent.succeeded イベント`をプログラムで取得できます。 ## イベントの保持 Workbench の **イベント** タブでは、過去 13 か月以内のイベントにアクセスできます。 - 15 日未満のイベントについては、完全なイベントペイロードを表示し、配信の試行を確認し、これらのイベントを手動で再送信できます。 - 16 ～ 30 日前のイベントについては、完全なイベントペイロードにアクセスできますが、再送信したり、配信の試行を表示したりすることはできません。 - 30 日以上経過したイベントの場合、サマリービューのみが表示され、元のイベントデータの不完全なフィールドが含まれます。これらのイベントでは、配信試行の再送信と表示は使用できません。 [Retrieve event](https://docs.stripe.com/api/v2/core/events/retrieve.md) API と [List events](https://docs.stripe.com/api/v2/core/events/list.md) API を使用して、過去 30 日間の全ペイロードを含むイベントにアクセスします。 ## イベント送信先の制限 本番環境またはサンドボックスアカウントにはそれぞれ、最大 16 件のイベント送信先を登録できます。加盟店のデフォルトバージョンとは異なるバージョンでスナップショットイベントの送信先を登録する場合、一意にバージョン管理されたスナップショットイベントの送信先を最大 3 件まで登録できます。 ## イベントの送信先を管理する ダッシュボードでイベントの送信先を作成、削除、更新するには、Workbench で [Webhook](https://dashboard.stripe.com/webhooks) タブを開くか、[event destinations API](https://docs.stripe.com/api/v2/event-destinations/.md) を使用します。 ## イベントの送信先を無効にする イベント送信先を無効にすることができます。イベント送信先を無効にすると、Stripe はその送信先へのイベント送信を停止します。デスティネーションを再度有効にすると、Stripe はそのデスティネーションへのイベント送信を再開します。