使用指南

Webhooks

Webhooks 使您的应用程序能够接收 PaymentKit 账户内发生的事件的实时通知，例如完成结账或更新订阅。您无需轮询 API 以获取变更，只需配置一个 Webhook 端点，PaymentKit 就会将包含事件详情的 HTTP POST 请求发送到您指定的 URL。
本指南将引导您使用 PaymentKit SDK 设置和管理 Webhook 端点。有关方法的完整列表，请参阅 Webhooks API 参考。
Webhook 流程#当您订阅的事件发生时，PaymentKit 会向您的服务器发送一个 POST 请求。您的服务器应处理此事件以自动执行后端任务，例如更新数据库、发送确认邮件或提供服务。
"您的 Webhook 服务器""PaymentKit 系统""用户操作""您的 Webhook 服务器""PaymentKit 系统""用户操作"完成结账生成 'checkout.session.completed' 事件向您配置的 URL 发送 HTTP POST以 2xx 状态响应以确认接收处理事件（例如，履行订单）

Webhook 端点对象#Webhook 端点对象包含用于接收事件的配置。以下是其主要属性：
Attribute
Type
Description
id
string
Webhook 端点的唯一标识符。
url
string
将发送 Webhook 事件的 URL。
enabled_events
string[]
此端点订阅的事件类型列表。
status
string
端点的当前状态，可以是 "enabled" 或 "disabled"。
description
string
端点的可选描述。
api_version
string
用于创建端点的 API 版本。
livemode
boolean
指示对象是在生产模式 (true) 还是测试模式 (false) 下创建的。
created_at
Date
端点创建时的时间戳。
创建 Webhook 端点#要开始接收事件，请创建一个 Webhook 端点并指定您想要监控的事件。
参数
Name
Type
Description
url
string
必需。 用于接收 Webhook POST 请求的服务器 URL。
enabled_events
string[]
必需。 要订阅的事件类型字符串数组。请参阅下面可用的事件完整列表。
description
string
可选描述，便于识别。
示例
import payment from '@blocklet/payment-js';

async function setupWebhook() {
  try {
    const webhook = await payment.webhookEndpoints.create({
      url: 'https://example.com/webhook-handler',
      enabled_events: [
        'checkout.session.completed',
        'customer.subscription.created',
        'customer.subscription.deleted'
      ],
      description: '用于主要应用程序事件的 Webhook'
    });
    console.log('Webhook 端点已创建：', webhook);
  } catch (error) {
    console.error('创建 Webhook 端点时出错：', error.message);
  }
}

setupWebhook();响应示例
{
  "id": "wh_1234567890abcdef",
  "livemode": false,
  "api_version": "1.0.0",
  "url": "https://example.com/webhook-handler",
  "description": "用于主要应用程序事件的 Webhook",
  "enabled_events": [
    "checkout.session.completed",
    "customer.subscription.created",
    "customer.subscription.deleted"
  ],
  "metadata": {},
  "status": "enabled",
  "created_at": "2023-10-27T10:00:00.000Z",
  "created_via": "api",
  "updated_at": "2023-10-27T10:00:00.000Z"
}列出 Webhook 端点#检索所有 Webhook 端点的分页列表。
参数
Name
Type
Description
page
number
要检索的页码。默认为 1。
pageSize
number
每页返回的端点数量。默认为 20。
order
string
结果的排序顺序，例如 "created_at:DESC"。
示例
import payment from '@blocklet/payment-js';

async function listWebhooks() {
  try {
    const webhooks = await payment.webhookEndpoints.list({ pageSize: 5 });
    console.log(`找到 ${webhooks.count} 个 Webhook：`);
    webhooks.list.forEach(wh => {
      console.log(`- ${wh.id} (${wh.url})`);
    });
  } catch (error) {
    console.error('列出 Webhook 时出错：', error.message);
  }
}

listWebhooks();响应示例
{
  "count": 1,
  "list": [
    {
      "id": "wh_1234567890abcdef",
      "livemode": false,
      "api_version": "1.0.0",
      "url": "https://example.com/webhook-handler",
      "description": "用于主要应用程序事件的 Webhook",
      "enabled_events": [
        "checkout.session.completed",
        "customer.subscription.created"
      ],
      "metadata": {},
      "status": "enabled",
      "created_at": "2023-10-27T10:00:00.000Z",
      "created_via": "api",
      "updated_at": "2023-10-27T10:00:00.000Z"
    }
  ]
}更新 Webhook 端点#修改现有的 Webhook 端点，例如更改其 URL 或已启用的事件列表。
参数
Name
Type
Description
id
string
必需。 要更新的 Webhook 端点的 ID。
data
object
必需。 包含要更新字段的对象。
data 对象的字段
Name
Type
Description
url
string
端点的新 URL。
enabled_events
string[]
新的事件类型列表。这将替换现有列表。
description
string
更新后的描述。
status
string
设置为 "enabled" 或 "disabled"。
示例
import payment from '@blocklet/payment-js';

async function updateWebhook(id) {
  try {
    const updatedWebhook = await payment.webhookEndpoints.update(id, {
      description: '更新后的 Webhook 描述',
      status: 'disabled'
    });
    console.log('Webhook 已更新：', updatedWebhook);
  } catch (error) {
    console.error('更新 Webhook 时出错：', error.message);
  }
}

updateWebhook('wh_1234567890abcdef');删除 Webhook 端点#如果不再需要某个 Webhook 端点，您可以将其永久删除。
参数
Name
Type
Description
id
string
必需。 要删除的 Webhook 端点的 ID。
示例
import payment from '@blocklet/payment-js';

async function deleteWebhook(id) {
  try {
    const deletedWebhook = await payment.webhookEndpoints.del(id);
    console.log(`Webhook ${deletedWebhook.id} 已被删除。`);
  } catch (error) {
    console.error('删除 Webhook 时出错：', error.message);
  }
}

deleteWebhook('wh_1234567890abcdef');可用事件类型#您可以订阅多种事件。以下是一些最常见的类别和事件类型：
结账
checkout.session.completed
checkout.session.expired
checkout.session.nft_minted
客户与订阅
customer.created
customer.deleted
customer.updated
customer.subscription.created
customer.subscription.updated
customer.subscription.deleted
customer.subscription.paused
customer.subscription.resumed
customer.subscription.renewed
customer.subscription.renew_failed
支付与退款
payment_intent.created
payment_intent.succeeded
payment_intent.payment_failed
refund.created
refund.succeeded
信用计费
customer.credit.insufficient
customer.credit_grant.granted
customer.credit_grant.low_balance
customer.credit_grant.depleted
这不是一个详尽的列表。请参考 EventType 定义以获取所有可能的值。

管理 Webhooks 对于构建响应迅速的自动化支付系统至关重要。现在，您可以创建端点来监听重要事件并实时对其采取行动。要了解更多关于处理支付的信息，请继续阅读 结账会话 指南。

Attribute	Type	Description
`id`	`string`	Webhook 端点的唯一标识符。
`url`	`string`	将发送 Webhook 事件的 URL。
`enabled_events`	`string[]`	此端点订阅的事件类型列表。
`status`	`string`	端点的当前状态，可以是 `"enabled"` 或 `"disabled"`。
`description`	`string`	端点的可选描述。
`api_version`	`string`	用于创建端点的 API 版本。
`livemode`	`boolean`	指示对象是在生产模式 (`true`) 还是测试模式 (`false`) 下创建的。
`created_at`	`Date`	端点创建时的时间戳。

Name	Type	Description
`url`	`string`	必需。用于接收 Webhook POST 请求的服务器 URL。
`enabled_events`	`string[]`	必需。要订阅的事件类型字符串数组。请参阅下面可用的事件完整列表。
`description`	`string`	可选描述，便于识别。

Name	Type	Description
`page`	`number`	要检索的页码。默认为 `1`。
`pageSize`	`number`	每页返回的端点数量。默认为 `20`。
`order`	`string`	结果的排序顺序，例如 `"created_at:DESC"`。

Name	Type	Description
`id`	`string`	必需。要更新的 Webhook 端点的 ID。
`data`	`object`	必需。包含要更新字段的对象。

Name	Type	Description
`url`	`string`	端点的新 URL。
`enabled_events`	`string[]`	新的事件类型列表。这将替换现有列表。
`description`	`string`	更新后的描述。
`status`	`string`	设置为 `"enabled"` 或 `"disabled"`。

概述

快速入门

核心概念

使用指南

API 参考

TypeScript 支持

Webhooks

Webhook 流程#

Webhook 端点对象#

创建 Webhook 端点#

列出 Webhook 端点#

更新 Webhook 端点#

删除 Webhook 端点#

可用事件类型#

退款

API 参考