イベントとの連携

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 のみが含まれます
イベントを処理するための追加データにアクセスします。	API から最新のオブジェクト定義を取得します。イベントペイロードのオブジェクト定義は、イベントを処理する時点で古くなっている可能性があります。	API から最新のオブジェクトを取得するか、`v2/events` から完全なイベントを取得します。完全なイベントペイロードには、イベントに関する追加の詳細が含まれる場合があります。たとえば、`v1.billing.meter.error_report_triggered` イベントのペイロードには、発生したエラーの種類と頻度に関する情報が含まれます。
SDK のタイプ指定	タイプ未指定	タイプ指定
バージョン管理	API バージョンによるバージョン管理	バージョン管理されないため、Webhook エンドポイント設定を変更することなく、システムをアップグレードできます

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

thin イベント

thin イベントは、API v2 名前空間を介してアクセスできる軽量イベントです。thin イベントはきめ細かい権限モデルを使用し、そのペイロードには API バージョン管理されたデータは含まれず、イベントに関連するオブジェクトの ID のみが含まれます。これにより、イベントを受信し、適切に型付けされた Stripe SDK で構築された実装を更新しやすくなります。thin イベントは以下のとおりです。

イベントの追加情報を含めることができる 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"
  }
}

スナップショットイベントペイロードの例

次の setup_intent.created スナップショットイベントの例では、イベントが発生したときのオブジェクト定義が含まれています。

{
  "id": "evt_1NG8Du2eZvKYlo2CUI79vXWy",
  "object": "event",
  "api_version": "2019-02-19",
  "created": 1686089970,

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

軽量イベントに関連して取得できる情報には、次の 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 を取得することが可能です。

イベントの保持

Workbench の イベント タブでは、過去 13 か月以内のイベントにアクセスできます。

15 日未満のイベントについては、完全なイベントペイロードを表示し、配信の試行を確認し、これらのイベントを手動で再送信できます。
16 ～ 30 日前のイベントについては、完全なイベントペイロードにアクセスできますが、再送信したり、配信の試行を表示したりすることはできません。
30 日以上経過したイベントの場合、サマリービューのみが表示され、元のイベントデータの不完全なフィールドが含まれます。これらのイベントでは、配信試行の再送信と表示は使用できません。

Retrieve event API と List events API を使用して、過去 30 日間の完全なペイロードを含むイベントにアクセスします。

イベント送信先の制限

本番環境またはサンドボックスアカウントにはそれぞれ、最大 16 件のイベント送信先を登録できます。加盟店のデフォルトバージョンとは異なるバージョンでスナップショットイベントの送信先を登録する場合、一意にバージョン管理されたスナップショットイベントの送信先を最大 3 件まで登録できます。

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

ダッシュボードでイベントの送信先を作成、削除、更新するには、Workbench で Webhook タブを開くか、event destinations API を使用します。

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

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