跳到主要内容

Webhook 端点

Webhook 端点允许 PaymentKit 向您的服务器发送异步事件通知。这对于处理成功付款、订阅更新或收费失败等事件至关重要。通过创建和管理 Webhook 端点，您可以确保您的应用程序与付款和客户的状态保持同步。

有关保护 Webhook 的概念性概述和最佳实践，请参阅我们的指南 Webhooks。

创建 Webhook 端点

创建一个新端点，用于从 PaymentKit 接收 Webhook 事件。

参数

名称类型描述必填
urlstring将接收 Webhook 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: 'Endpoint for production events',
    });
    console.log('Webhook Endpoint Created:', endpoint);
  } catch (error) {
    console.error('Error creating webhook endpoint:', error.message);
  }
}

createWebhookEndpoint();

示例响应

Response

json
{
  "id": "we_1a2b3c4d5e6f7g8h",
  "url": "https://example.com/my/webhook/handler",
  "description": "Endpoint for production events",
  "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 端点的详细信息。

参数

名称类型描述必填
idstringWebhook 端点的唯一标识符。是

返回值

返回与提供的 ID 对应的 WebhookEndpoint 对象。

示例

Retrieve Endpoint

javascript
async function retrieveWebhookEndpoint(endpointId) {
  try {
    const endpoint = await payment.webhookEndpoints.retrieve(endpointId);
    console.log('Retrieved Webhook Endpoint:', endpoint);
  } catch (error) {
    console.error('Error retrieving webhook endpoint:', error.message);
  }
}

retrieveWebhookEndpoint('we_1a2b3c4d5e6f7g8h');

更新 Webhook 端点

通过设置传入参数的值来更新现有的 Webhook 端点。

参数

名称类型描述必填
idstring要更新的 Webhook 端点的标识符。是
urlstring将接收 Webhook 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: 'New updated description',
      status: 'disabled',
    });
    console.log('Webhook Endpoint Updated:', endpoint);
  } catch (error) {
    console.error('Error updating webhook endpoint:', error.message);
  }
}

updateWebhookEndpoint('we_1a2b3c4d5e6f7g8h');

列出所有 Webhook 端点

返回所有 Webhook 端点的分页列表。

参数

名称类型描述必填
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(`Found ${endpoints.count} enabled endpoints:`);
    endpoints.list.forEach(ep => console.log(`- ${ep.id} (${ep.url})`));
  } catch (error) {
    console.error('Error listing webhook endpoints:', error.message);
  }
}

listWebhookEndpoints();

删除 Webhook 端点

永久删除一个 Webhook 端点。此操作不可逆。

参数

名称类型描述必填
idstring要删除的 Webhook 端点的唯一标识符。是

返回值

返回已删除的 WebhookEndpoint 对象。

示例

Delete Endpoint

javascript
async function deleteWebhookEndpoint(endpointId) {
  try {
    const deletedEndpoint = await payment.webhookEndpoints.del(endpointId);
    console.log('Webhook Endpoint Deleted:', deletedEndpoint);
  } catch (error) {
    console.error('Error deleting webhook endpoint:', error.message);
  }
}

deleteWebhookEndpoint('we_1a2b3c4d5e6f7g8h');

Webhook 端点对象

WebhookEndpoint 对象表示用于事件通知的已配置目标。

属性类型描述
idstringWebhook 端点对象的唯一标识符。
urlstring用于接收 Webhook POST 请求的端点 URL。
descriptionstring用户提供的端点可选描述。
enabled_eventsstring[]此端点订阅的事件类型列表。
statusstringWebhook 端点的当前状态（enabled 或 disabled）。
api_versionstring用于呈现发送到端点的事件数据的 API 版本。
livemodeboolean如果对象存在于生产模式，则为 true；如果处于测试模式，则为 false。
metadataobject附加到对象的一组键值对。
created_atstring表示对象创建时间的 ISO 8601 时间戳。
updated_atstring表示对象最后更新时间的 ISO 8601 时间戳。