Webhook エンドポイントを使用すると、PaymentKit はサーバーに非同期のイベント通知を送信できます。これは、支払いの成功、サブスクリプションの更新、請求の失敗などのイベントを処理するために不可欠です。Webhook エンドポイントを作成および管理することで、アプリケーションが支払いと顧客の状態を常に同期させることができます。
Webhook の保護に関する概念的な概要とベストプラクティスについては、ガイドWebhooks を参照してください。
Webhook エンドポイントの作成
PaymentKit からの Webhook イベントを受信するための新しいエンドポイントを作成します。
パラメータ
| Name | Type | Description | Required |
|---|---|---|---|
url | string | Webhook の POST リクエストを受信するサーバーの URL。 | はい |
enabled_events | string[] | このエンドポイントに送信したいイベントタイプの配列。 | はい |
description | string | Webhook エンドポイントの任意の説明。 | いいえ |
status | 'enabled' | 'disabled' | 任意。エンドポイントのステータス。指定しない場合、デフォルトは enabled です。 | いいえ |
metadata | Record<string, any> | 任意。参照用にオブジェクトに添付できるキーと値のペアのセット。 | いいえ |
戻り値
呼び出しが成功した場合、作成された WebhookEndpoint オブジェクトを返します。
例
Create Endpoint
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
{
"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 エンドポイントの詳細を取得します。
パラメータ
| Name | Type | Description | Required |
|---|---|---|---|
id | string | Webhook エンドポイントの一意の識別子。 | はい |
戻り値
指定された ID に対応する WebhookEndpoint オブジェクトを返します。
例
Retrieve Endpoint
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 エンドポイントを更新します。
パラメータ
| Name | Type | Description | Required |
|---|---|---|---|
id | string | 更新する Webhook エンドポイントの識別子。 | はい |
url | string | Webhook の POST リクエストを受信するサーバーの URL。 | いいえ |
description | string | Webhook エンドポイントの任意の説明。 | いいえ |
enabled_events | string[] | このエンドポイントに送信したいイベントタイプの配列。 | いいえ |
status | 'enabled' | 'disabled' | エンドポイントのステータス。disabled を使用してイベントの送信を一時的に停止します。 | いいえ |
metadata | Record<string, any> | オブジェクトに添付できるキーと値のペアのセット。 | いいえ |
戻り値
更新された WebhookEndpoint オブジェクトを返します。
例
Update Endpoint
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 エンドポイントのページ分割されたリストを返します。
パラメータ
| Name | Type | Description | Required |
|---|---|---|---|
status | string | 任意。絞り込むためのステータスのカンマ区切りリスト (例: 'enabled' または 'enabled,disabled')。 | いいえ |
page | number | 任意。ページネーション用のページ番号で、1から始まります。デフォルトは 1 です。 | いいえ |
pageSize | number | 任意。ページごとに返すアイテム数で、1から100の間です。デフォルトは 20 です。 | いいえ |
戻り値
WebhookEndpoint オブジェクトの list、合計アイテム数の count、および paging 情報を含むページ分割されたオブジェクトを返します。
例
List Endpoints
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 エンドポイントを永久に削除します。この操作は元に戻せません。
パラメータ
| Name | Type | Description | Required |
|---|---|---|---|
id | string | 削除する Webhook エンドポイントの一意の識別子。 | はい |
戻り値
削除された WebhookEndpoint オブジェクトを返します。
例
Delete Endpoint
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 オブジェクトは、イベント通知用に設定された宛先を表します。
| Attribute | Type | Description |
|---|---|---|
id | string | Webhook エンドポイントオブジェクトの一意の識別子。 |
url | string | Webhook の POST リクエストを受信するためのエンドポイントの URL。 |
description | string | ユーザーが提供する、エンドポイントの任意の説明。 |
enabled_events | string[] | このエンドポイントがサブスクライブしているイベントタイプのリスト。 |
status | string | Webhook エンドポイントの現在のステータス (enabled または disabled)。 |
api_version | string | エンドポイントに送信されるイベントデータをレンダリングするために使用される API バージョン。 |
livemode | boolean | オブジェクトがライブモードに存在する場合は true、テストモードの場合は false。 |
metadata | object | オブジェクトに添付されたキーと値のペアのセット。 |
created_at | string | オブジェクトが作成された日時を示す ISO 8601 タイムスタンプ。 |
updated_at | string | オブジェクトが最後に更新された日時を示す ISO 8601 タイムスタンプ。 |