イベントの送信先

Stripe から Webhook エンドポイントとクラウドサービスにイベントを送信します。

注

ワークベンチまたは開発者ダッシュボードにイベントの送信先タブが表示されない場合は、プロダクトのプレビューの設定でイベントの送信先を有効にします。

イベントの送信先を設定して、Stripe からのイベントを Webhook エンドポイントや Amazon EventBridge など、複数の送信先タイプで受信します。

さらに、API v2 エンドポイントによって作成される thin イベントを使用できます。API v2 の SDK には、アプリケーションで Stripe からオブジェクトの最新ステータスを取得できるヘルパーがあります。

ユースケース

Stripe のシステムを構築する際、自社のアプリが Stripe アカウントからイベントをリアルタイムで受信できるようにすることをお勧めします。こうすることで、バックエンドシステムはアクションへの応答とアクションの実行を適宜行うできます。

イベントの送信先では、Stripe はアカウントからリアルタイムのイベントデータのプッシュを行うことで、次のようなバックエンドアクションを実行できるようにします。

顧客が支払いを確認したときにユーザーに通知を送る
顧客が支払いに対して不審請求を申請したときに、内部の申し立ての調整プロセスを開始する
継続的なサブスクリプション支払いに成功したときにユーザーにアクセス権を付与する

対応している配送先タイプ

Amazon EventBridge を使用して AWS アカウントにイベントを送信するか、Webhook エンドポイント経由で HTTPS エンドポイントにイベントを送信します。

イベントの概要

Stripe はイベントデータを生成して、アカウントのアクティビティーに関する最新情報を通知します。

イベントが発生すると、Stripe は新しい Event オブジェクトを作成します。ご指定の送信先が Event を受信した後、アプリはバックエンドアクションを実行できます (たとえば、payment_intent.succeeded イベントを受信した後に、配送プロバイダーの API を呼び出して、配送の予定を設定します)。次の 2 種類の Event オブジェクトを提供しています。

thin イベント: これらのイベントには、影響を受けるオブジェクトの ID のみが含まれます。これらは API v2 endpoints によって生成されます。また、API v1 endpoints も thin イベントを生成します。thin イベントの全一覧をご覧ください。
スナップショットイベント: このイベントは、API v1 endpoints のみで生成され、変更されたオブジェクトの結果整合性のあるスナップショットを提供します。該当する場合は、変更を示す previous_attributes プロパティを含むことがあります。スナップショットイベントの全一覧をご覧ください。

この表では、thin イベントとスナップショットイベントの大まかな違いを示しています。

特性	スナップショットイベント	thin イベント
作成者	API v1 リソースのステータスの変化	API v2 リソースのステータスの変化
ペイロード	大容量: イベントに関連する API オブジェクトのスナップショットが含まれます	小容量: イベントに関連する API オブジェクトの ID のみが含まれます
SDK のタイプ指定	タイプ未指定	タイプ指定
バージョン管理	API バージョンによるバージョン管理	バージョン管理されないため、Webhook エンドポイント設定を変更することなく、システムをアップグレードできます

1 つの API リクエストで複数のイベントが作成されることがあります。たとえば、顧客に新しいサブスクリプションを作成すると、customer.subscription.created イベントと payment_intent.succeeded イベントが作成される場合があります。イベントの送信先ごとに、登録するイベントを選択します。

thin イベント

Thin events are lightweight events you can access through the API v2 namespace. Thin events have a more granular permissions model and their payloads contain no API-versioned data, only the IDs of the objects related to the event. This helps update integrations that receive events and are built with a well-typed Stripe SDK. Thin Events:

イベントの追加情報を含めることができる data プロパティを含めます。
SDKs for API v2 ですべてタイプが指定されています。

/v2/core/events エンドポイントから、各通知の Event オブジェクトを取得できます。これらの API オブジェクトには、シンイベントの追加の詳細を提供できる data プロパティが含まれています。

アプリケーションのエラーを防止

アプリケーションで、対応するイベント関連の API オブジェクト (Meter (従量) など) が必要な場合は、Stripe API を呼び出してオブジェクトの最新のステータスを取得する必要があります。この方法では、Stripe への追加のネットワークコールが必要になりますが、以前のオブジェクトデータに起因するアプリケーションエラー (競合状態など) を防止できます。SDKs for API v2 には、イベントに関連するレコードの取得を可能にするヘルパーメソッドが含まれています。

thin イベントのペイロード例

以下は、v1.billing.meter.error_report_triggered イベントの例です。related_object フィールドには、オブジェクトの id が含まれますが、オブジェクトレコード自体は含まれていません。

{
  "id": "evt_test_65R9Ijk8dKEYZcXeRWn16R9A7j1FSQ3w3TGDPLLGSM4CW0",
  "object": "v2.core.event",
  "type": "v1.billing.meter.error_report_triggered",
  "livemode": false,
  "created": "2024-09-17T06:20:52.246Z",
  "related_object": {
    "id": "mtr_test_61R9IeP0SgKbYROOx41PEAQhH0qO23oW",
    "type": "billing.meter",
    "url": "/v1/billing/meters/mtr_test_61R9IeP0SgKbYROOx41PEAQhH0qO23oW"
  }
}

そのため、thin イベントのペイロードはスナップショットイベントのペイロードよりもかなり小さくなります。比較のために、以下に invoice.created スナップショットイベントの例を示します。

{
  "object": {
    "id": "in_1KnN0G589O8KAxCGfVSpD0Pj",
    "object": "invoice",
    "account_country": "US",

軽量イベントに関連する追加情報を取得する

軽量イベントに関連して取得できる情報には、次の 2 つのタイプがあります。

関連するオブジェクトリソース定義: 各軽量イベントは、Stripe オブジェクトに関連する特定の発生内容の詳細を示します。イベントに関連付けられているオブジェクトの最新バージョンを取得するには、fetchRelatedObject() メソッドを使用します。たとえば、v1.billing.meter.error_report_triggered イベントを受信した場合、fetchRelatedObject() で、エラーレポートをトリガーした meter オブジェクトの最新バージョンを取得します。
追加のイベントペイロードフィールド: 軽量イベントには、 API でのみ取得可能な追加のコンテキストデータが含まれる場合があります。これらの追加のペイロードフィールドを取得するには、軽量イベント ID を指定して retrieve() コールを使用します。たとえば、API を使用して v1.billing.meter.error_report_triggered イベントを取得すると、追加の data ハッシュが返されます。このハッシュには、検証エラーが発生した時刻、サンプルのエラーメッセージの一覧、検証エラーの件数などの、トリガーされたエラーに関するフィールドが含まれています。

次の例は、軽量イベントに関連付けられている、関連するオブジェクト定義および追加のイベントペイロードフィールドを取得する方法を示しています。

イベントの権限

ダッシュボードでイベントを表示するには、ユーザーアカウントに管理者または開発者のロールを割り当てます。API を使用してイベントを取得するには、デフォルトですべてのイベントタイプを表示できるシークレット API キーを使用するか、特定のイベントタイプのリソースに対する Read アクセス権が有効になった制限付きの API キーを使用できます。たとえば、制限付きの API キーで payment_intent リソースへの Read アクセスを許可して、プログラムで payment_intent.succeeded events を取得することが可能です。

イベントの保持

ワークベンチのイベントタブでは過去 13 カ月以内に作成されたイベントにアクセスできますが、イベント送信セクションから手動で再送信したり表示できるのは 15 日未満の送信に限られます。30 日以上前のイベントについては、元のイベントデータの省略フィールドのみを含むサマリービューにアクセスできます。

Retrieve event と List events API v2 endpoints を使用して、過去 30 日以内の thin イベントにアクセスできます。過去 30 日以内のスナップショットイベントにアクセスするには、Retrieve event と List event API v1 endpoints を使用します。

イベントの送信先を管理する

ダッシュボードでイベントの送信先の作成、削除、更新を行うには、ワークベンチのイベントの送信先タブを開くか、Event Destinations API を使用します。

イベントの送信先を無効にする

イベントの送信先は無効にすることもできます。無効にすると、Stripe はその送信先へのイベントの送信を停止します。送信先を再度有効にすると、Stripe はその送信先へのイベントの送信を再開します。