# イベントとの連携 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 イベント](https://docs.stripe.com/api/v2/events.md): イベントデスティネーションに配信されると、Thin イベントは、影響を受けるオブジェクトの ID のみを含む軽量イベント通知として届きます。その後の API コールで、完全な `Event` オブジェクトまたは関連リソースの最新の状態をフェッチできます。これらは、API v2 endpoints によって生成されます。[Thin イベントの完全なリスト](https://docs.stripe.com/api/v2/core/events/event-types.md)を参照してください。 - [スナップショットイベント](https://docs.stripe.com/api/events.md): 宛先に配信されると、スナップショットイベントは、変更されたリソースの最終的に一貫性のあるスナップショットを持つ完全な `Event` オブジェクトとして届きます。このデータは処理するまでに古くなる可能性があるため、API からリソースの最新バージョンをフェッチすることを推奨します。Thin イベント通知とは異なり、配信されるスナップショットイベントはバージョン管理されているため、Stripe イベント送信先とクライアントの両方でバージョンを管理する必要があります。これらのイベントは API v1 endpoints によってのみ生成されます。これらのイベントには、`previous_attributes` プロパティが含まれ、該当する場合は変更を示します。[スナップショットイベントの全リスト](https://docs.stripe.com/api/events/types.md)を参照してください。 ### フォーマットの選択 Thin イベントは、以下のような場合に使用します。 - データの完全性は非常に重要であり、アプリケーションは最新の情報に基づいて実行されなければなりません。 - クライアントサイドだけでアップグレードを管理することで、バージョン管理を簡素化したいとお考えでしょう。 - モダンでタイプセーフなアプリケーションを構築しており、SDK の型付けの利点を活用したいと考えています。 スナップショットイベントは、次のような場合に使用します。 - その後の API コールを行わずに、変更された特定のフィールドを監査する必要があります。 - 導入するには、リソース定義のポイント・イン・タイム表示が必要であり、最終的に一貫性のあるデータを使用しても問題ありません。 この表では、thin イベントとスナップショットイベントの大まかな違いを示しています。 | 特性 | スナップショットイベント | thin イベント | | ------------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 作成者 | API v1 リソースのステータスの変化 | API v2 のリソース状態の変更 | | 配信されたペイロード | **大容量**: イベントに関連する API オブジェクトのスナップショットが含まれます | **小さい**: 軽量イベント通知にイベントに関連する 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) | ### Thin イベント通知ペイロードの例 以下は、`v2.core.account.updated` thin イベントの例です。`related_object` フィールドにはオブジェクトの `id` が含まれ、`reason` フィールドにはイベントをトリガーした内容が示され、`changes` フィールドにはオブジェクトで変更された内容が示されます。 ```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" }, "data": {}, "changes": { "before": { "display_name": "Example Account" }, "after": { "display_name": "Updated Example Account" } } } ``` ### スナップショットイベントのペイロード例 次の `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()` は、エラー報告をトリガーしたメーターオブジェクトを取得します。 1. **通知を直ちに処理します**: 通知のイベントタイプとリソース ID がユースケースに十分な場合、追加の API コールを行わずに処理できます。 以下の例は、Thin イベント通知を処理するときに関連する関連オブジェクト定義と追加イベントペイロードフィールドを取得する方法を示しています。 #### Java ```java com.stripe.model.EventNotification eventNotification = client.parseEventNotification(payload, signatureHeader, endpointSecret); com.stripe.model.v2.Event event = client.v2().core().events().retrieve(eventNotification.getId()); if (event instanceof V1BillingMeterErrorReportTriggeredEvent) { V1BillingMeterErrorReportTriggeredEvent postedEvent = (V1BillingMeterErrorReportTriggeredEvent) event; // On each type of event, the Stripe library provides a "fetchRelatedObject" method // that performs a network request to Stripe to fetch the latest version // of the object directly associated with the event, in this case, an // "Meter" object. Meter op = postedEvent.fetchRelatedObject(); } ``` ### SDK のタイプ指定 Thin イベントとその通知は SDK で完全に型付けされています。 - **イベント通知**: イベント宛先に配信される初期の軽量ペイロードは、`{EventType}EventNotification` として型付けされます。 - **Event**: `fetchEvent()` を使用して API から完全なイベントを取得した後、結果のオブジェクトは `{EventType}Event` として型付けされます。 ## イベントの権限 ダッシュボードでイベントを表示するには、ユーザーアカウントに[管理者または開発者のロール](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-secret-key)を使用できます。たとえば、制限付きの API キーで `payment_intent` リソースへの `Read` アクセスを許可して、プログラムで `payment_intent.succeeded events` を取得することが可能です。 ## イベントの保持 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 はそのデスティネーションへのイベント送信を再開します。