コンテンツにスキップ
アカウントを作成またはサインイン
Stripe ドキュメントのロゴ
/
アカウントを作成サインイン
概要
バージョン管理
API バージョンのアップグレード
Essentials
ツール
Visual Studio Code をご利用の場合
機能
Stripe 健全性アラートファイルのアップロード
AI ソリューション
モデルコンテキストプロトコルエージェントを使用した AI SaaS 請求ワークフローの構築
セキュリティとプライバシー
Stripebot ウェブクローラー
Stripe を拡張する
パートナー
パートナー認定

イベントとの連携

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

プライベートプレビュー

API v1リソースのシンイベントはプライベートプレビューで利用可能です。これらを使用すると、Webhook設定を変更することなく、統合のアップグレードを効率化できます。以前は、シンイベントはAPI v2リソースのみをサポートしていました。詳細を確認し、アクセスをリクエストしてください。

Webhook エンドポイント、Amazon EventBridge など、複数のデスティネーションタイプで Stripe からイベントを受信するイベントデスティネーションを設定します。イベントを受信するには、次のいずれかを実行します。

  • リソースをポイント・イン・タイムで表示するための自己完結型 スナップショットイベント
  • 軽量 Thin イベント、常に最新のデータに基づいて行動することを保証し、導入するアップグレードプロセスを簡素化します

ユースケース

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

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

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

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

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

イベントの概要

イベントが発生すると、Stripe は新しい Event オブジェクトを生成します。1 つの API リクエストで複数のイベントが生成される可能性があります。例えば、顧客に新しいサブスクリプションを作成すると、customer.subscription.created と payment_intent.succeeded イベントが発生する可能性があります。プログラムで導入する場合は、これらのイベントが発生したときに受信するようにイベント送信先を設定することを推奨します。イベントが構造化され、宛先に配信される方法は、受信するために選択したフォーマットによって異なります。

Event オブジェクトの 2 つの異なるフォーマットを提供します。

  • Thin イベント: イベントデスティネーションに配信されると、Thin イベントは、影響を受けるオブジェクトの ID のみを含む軽量イベント通知として届きます。その後の API コールで、完全な イベント オブジェクトまたは関連するリソースの最新の状態をフェッチできます。これらは、API v2 endpoints によって生成されます。これらは、 によって生成されます。Thin イベントの完全なリスト を参照してください。
  • スナップショットイベント: 宛先に配信されると、スナップショットイベントは、変更されたリソースの最終的に一貫性のあるスナップショットを持つ完全な イベント オブジェクトとして届きます。このデータは処理するまでに古くなる可能性があるため、API からリソースの最新バージョンをフェッチすることを推奨します。Thin イベント通知とは異なり、配信されるスナップショットイベントはバージョン管理されているため、Stripe イベント送信先とクライアントの両方でバージョンを管理する必要があります。これらのイベントは API v1 endpoints によってのみ生成されます。これらのイベントには、previous_attributes プロパティが含まれ、該当する場合は変更を示します。スナップショットイベントの全リスト を参照してください。

フォーマットの選択

Thin イベントは、以下のような場合に使用します。

  • データの完全性は非常に重要であり、アプリケーションは最新の情報に基づいて実行されなければなりません。
  • クライアントサイドだけでアップグレードを管理することで、バージョン管理を簡素化したいとお考えでしょう。
  • モダンでタイプセーフなアプリケーションを構築しており、SDK の型付けの利点を活用したいと考えています。

スナップショットイベントは、次のような場合に使用します。

  • その後の API コールを行わずに、変更された特定のフィールドを監査する必要があります。
  • 導入するには、リソース定義のポイント・イン・タイム表示が必要であり、最終的に一貫性のあるデータを使用しても問題ありません。

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

特性スナップショットイベントthin イベント
作成者API v1 リソースのステータスの変化API v2 のリソース状態の変更
配信されたペイロード大容量: イベントに関連する API オブジェクトのスナップショットが含まれます小さい: 軽量イベント通知にイベントに関連する API オブジェクトの ID を含みます
イベントを処理するための追加データへのアクセス。API から最新のオブジェクト定義を取得します。イベントペイロードのオブジェクト定義は、イベントを処理する時点で古くなっている可能性があります。API から最新のオブジェクトを取得するか、v2/events から イベント の完全なものを取得します。完全なイベントペイロードは、イベントに関する追加詳細を含むことができます。例えば、v1.billing.meter.error_report_triggered イベントのペイロードには、発生したエラーのタイプと頻度に関する情報が含まれます。
SDK のタイプ指定タイプ未指定タイプ指定
バージョン管理API バージョンによるバージョン管理バージョン管理されないため、Webhook エンドポイント設定を変更することなく、システムをアップグレードできます
イベントを表示する APIイベント v1 APIイベント v2 API

Thin イベント通知ペイロードの例

以下は v1.billing.meter.error_report_triggered イベントの例です。以下の data ハッシュは、宛先に送信されるイベント通知ではアクセスできません。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"
  }
  "data": {
    "developer_message_summary": "There is 1 invalid event",
    "reason": {
      "error_count": 1,
      "error_types": [
        {
          "code": "meter_event_no_customer_defined",
          "error_count": 1,
          "sample_errors": [
            {
              "error_message": "Customer mapping key stripe_customer_id not found in payload.",
              "request": {
                "id": "",
                "idempotency_key": "37c741d8-1f7e-4adc-af16-afdca1d73b37"
              }
            }
          ]
        }
      ]
    },
    "validation_end": "2024-08-28T20:54:10.000Z",
    "validation_start": "2024-08-28T20:54:00.000Z"
  }
}

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

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

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

Thin イベントの使用

API から詳細を取得するために、宛先に送信されたイベント通知を使用して、Thin イベントと導入します。

イベント通知の処理

初期通知には最小限のデータが含まれます。イベント通知を処理するとき、導入する必要がある情報に応じて、3 つのアプローチのいずれかを選択します。

  1. 完全なイベントの取得: fetchEvent() メソッドを使用して、完全な Event オブジェクトを取得します。完全なイベント・オブジェクトは、2 種類の追加データを含むことができます。
    • data ハッシュで利用可能な、イベント自体のコンテキスト情報。例えば、v1.billing.meter.error_report_triggered イベントは、このフィールドの検証エラーのタイプとサマリーに関する詳細を含みます。
    • changes ハッシュで利用可能な、リソース上で変更された属性の以前の値。

以下の表は、最初の通知と比較して、完全な イベント オブジェクトで利用可能な追加データの詳細を示しています。

プロパティ名イベント通知イベント
イベントタイプ✅✅
関連リソース ID✅✅
イベント ID✅✅
作成時点のタイムスタンプ✅✅
理由✅✅
変更点❌✅
データ❌✅
  1. 関連オブジェクトの最新の状態を取得します: fetchRelatedObject() メソッドを使用して、イベントに関連付けられたオブジェクトの最新バージョンを取得します。例えば、v1.billing.meter.error_report_triggered イベント を受信した場合、fetchRelatedObject() は、エラー報告をトリガーしたメーターオブジェクトを取得します。
  2. 通知を直ちに処理します: 通知のイベントタイプとリソース ID がユースケースに十分な場合、追加の API コールを行わずに処理できます。

以下の例は、Thin イベント通知を処理するときに関連する関連オブジェクト定義と追加イベントペイロードフィールドを取得する方法を示しています。

Java
Node.js
Python
.NET
Ruby
PHP
Go
No results
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 として型付けされます。

イベントの権限

ダッシュボードでイベントを表示するには、ユーザーアカウントに管理者または開発者のロールを割り当てます。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 はそのデスティネーションへのイベント送信を再開します。

このページはお役に立ちましたか。
はいいいえ