Webhooks
Webhooks 是一个强大的工具，用于接收关于您 PaymentKit 账户中发生的事件的实时通知，例如支付成功、订阅更新或扣款失败。通过设置一个 Webhook 端点，您可以根据这些事件自动化您的后端流程。
本文档为 Webhook 端点 API 提供了详细的参考。关于如何实现和保护 Webhook 的更高级别指南，请参阅 Webhooks 指南。
Webhook 端点对象#
一个 Webhook 端点对象包含有关要通知的 URL 和它应监听的特定事件的信息。
属性 | 类型 | 描述 |
|---|---|---|
|
| Webhook 端点的唯一标识符。 |
|
| 如果对象存在于实时模式下，则为 |
|
| 用于渲染发送到端点的事件数据的 API 版本。 |
|
| Webhook 端点的 URL。 |
|
| Webhook 端点的可选描述。 |
|
| 此端点配置为接收的事件类型列表。例如 |
|
| 一组可以附加到对象的键值对。可用于存储附加信息。 |
|
| Webhook 端点的状态，可以是 |
|
| 对象创建时的时间戳。 |
|
| 端点的创建方式，可以是 |
|
| 最后更新的时间戳。 |
创建一个 Webhook 端点#
创建一个新的 Webhook 端点以接收通知。
参数
名称 | 类型 | 描述 |
|---|---|---|
|
| 必需。 将通过 POST 请求发送事件通知的 URL。 |
|
| 必需。 您想要订阅的事件类型字符串数组。 |
|
| 端点的可选描述。 |
|
| 事件数据的 API 版本。默认为您账户的默认 API 版本。 |
|
| 与端点一起存储的可选键值数据。 |
|
| 端点的初始状态。可以是 |
返回
返回新创建的 Webhook 端点对象。
import payment from '@blocklet/payment-js';
async function createWebhookEndpoint() {
try {
const endpoint = await payment.webhooks.create({
url: 'https://example.com/webhook-receiver',
enabled_events: [
'charge.succeeded',
'customer.subscription.deleted'
],
description: 'Endpoint for production events'
});
console.log('Webhook 端点已创建:', endpoint.id);
return endpoint;
} catch (error) {
console.error('创建 Webhook 端点时出错:', error.message);
}
}
createWebhookEndpoint();响应示例
{
"id": "whep_123456789",
"livemode": false,
"api_version": "2024-01-01",
"url": "https://example.com/webhook-receiver",
"description": "Endpoint for production events",
"enabled_events": [
"charge.succeeded",
"customer.subscription.deleted"
],
"metadata": {},
"status": "enabled",
"created_at": "2024-05-21T10:00:00.000Z",
"created_via": "api",
"updated_at": "2024-05-21T10:00:00.000Z"
}检索一个 Webhook 端点#
通过 ID 检索现有 Webhook 端点的详细信息。
参数
名称 | 类型 | 描述 |
|---|---|---|
|
| 必需。 要检索的 Webhook 端点的唯一标识符。 |
返回
返回指定的 Webhook 端点对象。
import payment from '@blocklet/payment-js';
async function retrieveWebhookEndpoint(endpointId) {
try {
const endpoint = await payment.webhooks.retrieve(endpointId);
console.log('已检索的端点:', endpoint.url);
return endpoint;
} catch (error) {
console.error(`检索 Webhook 端点 ${endpointId} 时出错:`, error.message);
}
}
retrieveWebhookEndpoint('whep_123456789');响应示例
{
"id": "whep_123456789",
"livemode": false,
"api_version": "2024-01-01",
"url": "https://example.com/webhook-receiver",
"description": "Endpoint for production events",
"enabled_events": [
"charge.succeeded",
"customer.subscription.deleted"
],
"metadata": {},
"status": "enabled",
"created_at": "2024-05-21T10:00:00.000Z",
"created_via": "api",
"updated_at": "2024-05-21T10:00:00.000Z"
}更新一个 Webhook 端点#
更新现有的 Webhook 端点。您可以更改其 URL、监听的事件、描述或状态。
参数
名称 | 类型 | 描述 |
|---|---|---|
|
| 必需。 要更新的端点的标识符。 |
|
| 端点的新 URL。 |
|
| 要订阅的新事件类型列表。这将替换现有列表。 |
|
| 更新后的描述。 |
|
| 新状态，可以是 |
|
| 新的元数据。这将替换现有的元数据。 |
返回
返回更新后的 Webhook 端点对象。
import payment from '@blocklet/payment-js';
async function updateWebhookEndpoint(endpointId) {
try {
const endpoint = await payment.webhooks.update(endpointId, {
description: 'Updated endpoint description',
status: 'disabled'
});
console.log('Webhook 端点已更新:', endpoint.id, '状态:', endpoint.status);
return endpoint;
} catch (error) {
console.error(`更新 Webhook 端点 ${endpointId} 时出错:`, error.message);
}
}
updateWebhookEndpoint('whep_123456789');响应示例
{
"id": "whep_123456789",
"livemode": false,
"api_version": "2024-01-01",
"url": "https://example.com/webhook-receiver",
"description": "Updated endpoint description",
"enabled_events": [
"charge.succeeded",
"customer.subscription.deleted"
],
"metadata": {},
"status": "disabled",
"created_at": "2024-05-21T10:00:00.000Z",
"created_via": "api",
"updated_at": "2024-05-21T10:05:00.000Z"
}列出所有 Webhook 端点#
返回所有 Webhook 端点的分页列表。
参数
名称 | 类型 | 描述 |
|---|---|---|
|
| 分页的页码，从 1 开始。 |
|
| 每页返回的项目数。默认为 20。 |
| `string | string[]` |
返回
返回一个包含 Webhook 端点列表的分页对象。
名称 | 类型 | 描述 |
|---|---|---|
|
| 与查询匹配的端点总数。 |
|
| Webhook 端点对象数组。 |
import payment from '@blocklet/payment-js';
async function listWebhookEndpoints() {
try {
const endpoints = await payment.webhooks.list({ pageSize: 5 });
console.log(`共找到 ${endpoints.count} 个端点。`);
endpoints.list.forEach(endpoint => {
console.log(`- ${endpoint.id} (${endpoint.url})`);
});
return endpoints;
} catch (error) {
console.error('列出 Webhook 端点时出错:', error.message);
}
}
listWebhookEndpoints();响应示例
{
"count": 1,
"list": [
{
"id": "whep_123456789",
"livemode": false,
"api_version": "2024-01-01",
"url": "https://example.com/webhook-receiver",
"description": "Updated endpoint description",
"enabled_events": [
"charge.succeeded",
"customer.subscription.deleted"
],
"metadata": {},
"status": "disabled",
"created_at": "2024-05-21T10:00:00.000Z",
"created_via": "api",
"updated_at": "2024-05-21T10:05:00.000Z"
}
]
}删除一个 Webhook 端点#
永久删除一个 Webhook 端点。此操作无法撤销。
参数
名称 | 类型 | 描述 |
|---|---|---|
|
| 必需。 要删除的 Webhook 端点的唯一标识符。 |
返回
返回已删除的 Webhook 端点对象。
import payment from '@blocklet/payment-js';
async function deleteWebhookEndpoint(endpointId) {
try {
const endpoint = await payment.webhooks.del(endpointId);
console.log(`成功删除 Webhook 端点 ${endpoint.id}。`);
return endpoint;
} catch (error) {
console.error(`删除 Webhook 端点 ${endpointId} 时出错:`, error.message);
}
}
deleteWebhookEndpoint('whep_123456789');响应示例
{
"id": "whep_123456789",
"livemode": false,
"api_version": "2024-01-01",
"url": "https://example.com/webhook-receiver",
"description": "Updated endpoint description",
"enabled_events": [
"charge.succeeded",
"customer.subscription.deleted"
],
"metadata": {},
"status": "disabled",
"created_at": "2024-05-21T10:00:00.000Z",
"created_via": "api",
"updated_at": "2024-05-21T10:05:00.000Z"
}配置好您的 Webhook 后，您可能需要管理支付退款。请前往退款 API 参考了解更多信息。