イベントの送信先

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 のみが含まれます
Access additional data to process event.	Fetch the latest object definition from the API. The object definition in the event payload might be outdated by the time you process the event.	Fetch the latest object from the API or retrieve the full event from `v2/events`. The full event payload may include extra details about the event. For example, the payload for a `v1.billing.meter.error_report_triggered` event includes information about the types and frequency of errors raised.
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"
  }
}

Example snapshot event payload

View the following example of an setup_intent.created snapshot event, which includes the object definition as it was when the event was raised:

{
  "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 を取得することが可能です。

イベントの保持

In the Events tab in Workbench, you can access events within the last 13 months:

For events less than 15 days old, you can view the full event payload, see the delivery attempts, and manually resend these events.
For events 16-30 days old, you can access the full event payload, but you can’t resend them or view delivery attempts.
For events older than 30 days, you can only see a summary view, which includes truncated fields of the original event data. Resending and viewing delivery attempts aren’t available for these events.

Use the Retrieve event and List events APIs to access events with their full payload from the past 30 days.

Event destination limits

You can register a maximum of 16 event destinations in each livemode or sandbox account. When registering a snapshot event destination with a version different from your merchant’s default version, you can register up to three uniquely versioned snapshot event destinations.