メインコンテンツへスキップ

Webhook エンドポイント

Webhook エンドポイントを使用すると、PaymentKit はサーバーに非同期のイベント通知を送信できます。これは、支払いの成功、サブスクリプションの更新、請求の失敗などのイベントを処理するために不可欠です。Webhook エンドポイントを作成および管理することで、アプリケーションが支払いと顧客の状態を常に同期させることができます。

Webhook の保護に関する概念的な概要とベストプラクティスについては、ガイドWebhooks を参照してください。

Webhook エンドポイントの作成

PaymentKit からの Webhook イベントを受信するための新しいエンドポイントを作成します。

パラメータ

NameTypeDescriptionRequired
urlstringWebhook の POST リクエストを受信するサーバーの URL。はい
enabled_eventsstring[]このエンドポイントに送信したいイベントタイプの配列。はい
descriptionstringWebhook エンドポイントの任意の説明。いいえ
status'enabled' | 'disabled'任意。エンドポイントのステータス。指定しない場合、デフォルトは enabled です。いいえ
metadataRecord<string, any>任意。参照用にオブジェクトに添付できるキーと値のペアのセット。いいえ

戻り値

呼び出しが成功した場合、作成された WebhookEndpoint オブジェクトを返します。

Create Endpoint

javascript
async function createWebhookEndpoint() {
  try {
    const endpoint = await payment.webhookEndpoints.create({
      url: 'https://example.com/my/webhook/handler',
      enabled_events: [
        'checkout.session.completed',
        'customer.subscription.updated',
      ],
      description: '本番環境イベント用のエンドポイント',
    });
    console.log('Webhook エンドポイントが作成されました:', endpoint);
  } catch (error) {
    console.error('Webhook エンドポイントの作成エラー:', error.message);
  }
}

createWebhookEndpoint();

レスポンス例

Response

json
{
  "id": "we_1a2b3c4d5e6f7g8h",
  "url": "https://example.com/my/webhook/handler",
  "description": "本番環境イベント用のエンドポイント",
  "enabled_events": [
    "checkout.session.completed",
    "customer.subscription.updated"
  ],
  "status": "enabled",
  "api_version": "2023-09-05",
  "livemode": false,
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "metadata": {}
}

Webhook エンドポイントの取得

一意の識別子によって、既存の Webhook エンドポイントの詳細を取得します。

パラメータ

NameTypeDescriptionRequired
idstringWebhook エンドポイントの一意の識別子。はい

戻り値

指定された ID に対応する WebhookEndpoint オブジェクトを返します。

Retrieve Endpoint

javascript
async function retrieveWebhookEndpoint(endpointId) {
  try {
    const endpoint = await payment.webhookEndpoints.retrieve(endpointId);
    console.log('取得した Webhook エンドポイント:', endpoint);
  } catch (error) {
    console.error('Webhook エンドポイントの取得エラー:', error.message);
  }
}

retrieveWebhookEndpoint('we_1a2b3c4d5e6f7g8h');

Webhook エンドポイントの更新

渡されたパラメータの値を設定することで、既存の Webhook エンドポイントを更新します。

パラメータ

NameTypeDescriptionRequired
idstring更新する Webhook エンドポイントの識別子。はい
urlstringWebhook の POST リクエストを受信するサーバーの URL。いいえ
descriptionstringWebhook エンドポイントの任意の説明。いいえ
enabled_eventsstring[]このエンドポイントに送信したいイベントタイプの配列。いいえ
status'enabled' | 'disabled'エンドポイントのステータス。disabled を使用してイベントの送信を一時的に停止します。いいえ
metadataRecord<string, any>オブジェクトに添付できるキーと値のペアのセット。いいえ

戻り値

更新された WebhookEndpoint オブジェクトを返します。

Update Endpoint

javascript
async function updateWebhookEndpoint(endpointId) {
  try {
    const endpoint = await payment.webhookEndpoints.update(endpointId, {
      description: '新しい更新された説明',
      status: 'disabled',
    });
    console.log('Webhook エンドポイントが更新されました:', endpoint);
  } catch (error) {
    console.error('Webhook エンドポイントの更新エラー:', error.message);
  }
}

updateWebhookEndpoint('we_1a2b3c4d5e6f7g8h');

すべての Webhook エンドポイントを一覧表示

すべての Webhook エンドポイントのページ分割されたリストを返します。

パラメータ

NameTypeDescriptionRequired
statusstring任意。絞り込むためのステータスのカンマ区切りリスト (例: 'enabled' または 'enabled,disabled')。いいえ
pagenumber任意。ページネーション用のページ番号で、1から始まります。デフォルトは 1 です。いいえ
pageSizenumber任意。ページごとに返すアイテム数で、1から100の間です。デフォルトは 20 です。いいえ

戻り値

WebhookEndpoint オブジェクトの list、合計アイテム数の count、および paging 情報を含むページ分割されたオブジェクトを返します。

List Endpoints

javascript
async function listWebhookEndpoints() {
  try {
    const endpoints = await payment.webhookEndpoints.list({
      status: 'enabled',
      pageSize: 5,
    });
    console.log(`有効なエンドポイントが ${endpoints.count} 個見つかりました:`);
    endpoints.list.forEach(ep => console.log(`- ${ep.id} (${ep.url})`));
  } catch (error) {
    console.error('Webhook エンドポイントの一覧表示エラー:', error.message);
  }
}

listWebhookEndpoints();

Webhook エンドポイントの削除

Webhook エンドポイントを永久に削除します。この操作は元に戻せません。

パラメータ

NameTypeDescriptionRequired
idstring削除する Webhook エンドポイントの一意の識別子。はい

戻り値

削除された WebhookEndpoint オブジェクトを返します。

Delete Endpoint

javascript
async function deleteWebhookEndpoint(endpointId) {
  try {
    const deletedEndpoint = await payment.webhookEndpoints.del(endpointId);
    console.log('Webhook エンドポイントが削除されました:', deletedEndpoint);
  } catch (error) {
    console.error('Webhook エンドポイントの削除エラー:', error.message);
  }
}

deleteWebhookEndpoint('we_1a2b3c4d5e6f7g8h');

Webhook エンドポイントオブジェクト

WebhookEndpoint オブジェクトは、イベント通知用に設定された宛先を表します。

AttributeTypeDescription
idstringWebhook エンドポイントオブジェクトの一意の識別子。
urlstringWebhook の POST リクエストを受信するためのエンドポイントの URL。
descriptionstringユーザーが提供する、エンドポイントの任意の説明。
enabled_eventsstring[]このエンドポイントがサブスクライブしているイベントタイプのリスト。
statusstringWebhook エンドポイントの現在のステータス (enabled または disabled)。
api_versionstringエンドポイントに送信されるイベントデータをレンダリングするために使用される API バージョン。
livemodebooleanオブジェクトがライブモードに存在する場合は true、テストモードの場合は false
metadataobjectオブジェクトに添付されたキーと値のペアのセット。
created_atstringオブジェクトが作成された日時を示す ISO 8601 タイムスタンプ。
updated_atstringオブジェクトが最後に更新された日時を示す ISO 8601 タイムスタンプ。