Connect Webhook
アカウントでイベントが発生すると、Stripe は Webhook を使用してアプリケーションに通知します。すべての Connect の組み込みでは、Webhook エンドポイントを設定して、Connect イベントをリッスンする必要があります。
Connect Webhook
Webhook にはいくつかのタイプがあります。
- 「アカウント」Webhook は、自身のアカウントでのアクティビティー (API キーを使用し、別の Stripe アカウントとしての認証なしで行われるほとんどのリクエストなど) 用です。これには、連結アカウントで直接行われたものを除き、すべてのタイプの支払いが含まれます。
- _「Connect」_Webhook は、連結アカウントでのアクティビティー用です。連結アカウントのすべてのイベントは Connect Webhook に送信されます。連結アカウントとダイレクト支払いに関する重要な
account.updated
イベントが含まれます。
Webhook を作成する際には、Connect Webhook イベントを受信するように正しく設定されていることを確認してください。これを行うには、API で Webhook エンドポイントの作成時に connect パラメータを true
に設定するか、ダッシュボードを使用します。
Connect Webhook では、開発環境の Webhook URL にはテスト Webhook のみが送信され、本番環境の Webhook URL には「本番とテストの両方」の Webhook が送信されることに注意してください。これは、本番環境アプリケーションで本番取引とテスト取引の両方を実行できるためです。このため、イベントの Webhook を受信したら livemode
の値を確認して、必要なアクションがある場合は、それを確認することをお勧めします。
Event オブジェクトのリファレンスに記載されているように、連結アカウントの各イベントには、最上位の account
プロパティも含まれます。このプロパティは、Webhook の送信先のアカウントと、そのアカウントが属する data[object]
を識別します。これらのオブジェクトは別のアカウントに属しているため、アクセスするには、対応する連結アカウントとして API リクエストを行う必要があります。
{ "id":
, "livemode": true, "object": "event", "type": "customer.created", "account":"{{EVENT_ID}}", "pending_webhooks": 2, "created": 1349654313, "data": {...} }"{{CONNECTED_ACCOUNT_ID}}"
アカウントに関連するイベントでリッスンが推奨されるものを以下に示します。
イベント | data.object type | 説明 |
---|---|---|
account.application.deauthorized | application | Occurs when a connected account disconnects from your platform. You can use it to trigger cleanup on your server. Available for connected accounts with access to the Stripe Dashboard, which includes Standard accounts. |
account.external_account.updated | card やbank_account などの外部口座 | 連結アカウントに関連付けられた銀行口座またはデビットカードが更新された場合に発生し、入金に影響することがあります。プラットフォームで管理される連結アカウントに適用されます。これには、Custom アカウントと Express アカウント、およびプラットフォーム管理が有効な Standard アカウントが含まれます。 |
account.updated | account | 連結アカウントの要件に対する変更とステータスの変化を監視できます。すべての連結アカウントで利用可能です。 |
balance.available | balance | Occurs when your Stripe balance has been updated (for example, when funds you’ve added from your bank account are available for transfer to your connected account). |
payment_intent.succeeded | payment_intent | Occurs when a payment intent results in a successful charge. Available for all payments, including destination and direct charges. |
payout.failed | payout | Occurs when a payout fails. When a payout fails, the external account involved will be disabled, and no automatic or manual payouts can go through until the external account is updated. |
person.updated | person | Persons API を使用すると、個人の要件の変更とステータスの変更を監視できるようになります。プラットフォームで管理される連結アカウントに適用されます。これには、Custom アカウントと Express アカウント、およびプラットフォーム管理が有効な Standard アカウントが含まれます。 |
上記のイベントは、Connect の組み込みでリッスンが推奨される典型的なイベントですが、その他多くのイベントタイプもご利用いただけます。
Webhook をローカルでテストする
Stripe CLI を使用して、Webhook をローカルでテストできます。
まだインストールしていない場合は、マシンに Stripe CLI をインストールします。
Stripe アカウントにログインし、コマンドラインで
stripe login
を実行して CLI を設定します。1 つの端末ウィンドウで
stripe listen --forward-to localhost:{PORT}/webhook
を実行し、別の端末ウィンドウでstripe trigger {{EVENT_NAME}}
を実行することにより、ローカルホストがシミュレーションされたイベントを連結アカウントで受信できるようにします。
注
Connect Webhook では、stripe listen
で --forward-connect-to
を使用し、stripe trigger
で --stripe-account
を使用します。