Webhook 端点

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

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

创建 Webhook 端点#

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

参数#

名称

类型

描述

必填

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: 'Endpoint for production events',
    });
    console.log('Webhook Endpoint Created:', endpoint);
  } catch (error) {
    console.error('Error creating webhook endpoint:', error.message);
  }
}

createWebhookEndpoint();

示例响应#

Response

{
  "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 端点的详细信息。

参数#

名称

类型

描述

必填

id

string

Webhook 端点的唯一标识符。

是

返回值#

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

示例#

Retrieve Endpoint

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 端点。

参数#

名称

类型

描述

必填

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: '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 端点的分页列表。

参数#

名称

类型

描述

必填

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(`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 端点。此操作不可逆。

参数#

名称

类型

描述

必填

id

string

要删除的 Webhook 端点的唯一标识符。

是

返回值#

返回已删除的 WebhookEndpoint 对象。

示例#

Delete Endpoint

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 对象表示用于事件通知的已配置目标。

属性

类型

描述

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 时间戳。

订阅