跳到主要内容

Webhooks（Webhook）

使用 Webhook 资源注册并管理 HTTPS 回调端点（URL、订阅事件、签名密钥）。SDK 仅覆盖管理 API — 校验入站 Webhook 投递须由你的应用实现（签名规则见主站 API 文档）。

事件类型： 在 subscribedEvents 中仅使用受支持的标识符。全部受支持标识符见 事件列表（与主站 事件列表 一致）。

访问 Webhook API​

所有 Webhook 管理操作都通过 GStableClient 实例上的 client.webhook 完成。

错误处理​

当 API 返回非零 code 或传输层失败时，会抛出 GStableError 或其子类（例如无效 URL、权限问题等）。

import { GStableClient, GStableError } from 'gstable-js';

const client = new GStableClient({ apiKey: process.env.GSTABLE_API_KEY! });

try {
  await client.webhook.create({
    webhookName: 'Production ledger',
    webhookUrl: 'https://api.example.com/hooks/gstable',
    subscribedEvents: ['payment.completed'],
  });
} catch (error) {
  if (error instanceof GStableError) {
    console.error(`GStable error [${error.code}]: ${error.message}`);
  }
}

TypeScript 类型​

为 Webhook 注册与响应提供类型定义，可从包根路径导入。

核心类型

  • Webhook — create / detail 返回的端点记录（webhookId、URL、subscribedEvents、key、status、时间戳等，以 API 为准）。
  • WebhookStatus — 端点投递 / 生命周期状态。

请求体

  • CreateWebhookBody — 注册新端点（名称、HTTPS URL、事件列表、可选描述）。
  • UpdateWebhookBody — 全量替换字段，含 webhookId。

响应包装

  • WebhookListData — list 返回的 { webhooks: Webhook[] }。
  • OperationSuccess — update、enable、disable、refreshKey、remove 等成功信封。
import type {
  Webhook,
  WebhookStatus,
  CreateWebhookBody,
  UpdateWebhookBody,
  WebhookListData,
  OperationSuccess,
} from 'gstable-js';

create​

client.webhook.create(body)

参数​

名称类型必填说明
bodyCreateWebhookBody是注册载荷。

CreateWebhookBody：

字段类型必填说明
webhookNamestring是展示名称。
webhookUrlstring是你对外暴露的 HTTPS 回调 URL。
subscribedEventsstring[]是事件类型字符串 — 见 事件列表。
webhookDescriptionstring否可选备注。

返回值​

Promise<Webhook> — 含 webhookId、key（签名密钥 — 请安全保存）、status、时间戳等。

示例​

import { GStableClient } from 'gstable-js';

const client = new GStableClient({ apiKey: process.env.GSTABLE_API_KEY! });

const hook = await client.webhook.create({
  webhookName: 'Production ledger',
  webhookUrl: 'https://api.example.com/hooks/gstable',
  subscribedEvents: ['payment.completed'],
});

console.log(hook.webhookId, hook.key);

update​

对 Webhook 元数据执行全量替换（「全量替换」语义）。

client.webhook.update(body)

参数​

名称类型必填说明
bodyUpdateWebhookBody是须包含 webhookId。

UpdateWebhookBody：

字段类型必填说明
webhookIdstring是目标端点。
webhookNamestring是新名称。
webhookUrlstring是新 URL。
subscribedEventsstring[]是替换订阅列表。
webhookDescriptionstring否可选。

返回值​

Promise<OperationSuccess>

示例​

await client.webhook.update({
  webhookId: 'wh_xxx',
  webhookName: 'Production ledger',
  webhookUrl: 'https://api.example.com/hooks/gstable',
  subscribedEvents: ['payment.completed', 'payment.failed'],
});

list​

client.webhook.list()

参数​

无。

返回值​

Promise<WebhookListData> — { webhooks: Webhook[] }（账户下完整列表）。

示例​

const { webhooks } = await client.webhook.list();
console.log(webhooks.map((w) => w.webhookId));

detail​

client.webhook.detail(webhookId)

参数​

名称类型必填说明
webhookIdstring是Webhook id。

返回值​

Promise<Webhook>

示例​

const w = await client.webhook.detail('wh_xxx');
console.log(w.subscribedEvents, w.status);

disable​

client.webhook.disable(webhookId)

参数​

名称类型必填说明
webhookIdstring是Webhook id。

返回值​

Promise<OperationSuccess>

示例​

await client.webhook.disable('wh_xxx');

enable​

恢复投递；可按平台规则从 paused 等状态恢复。

client.webhook.enable(webhookId)

参数​

名称类型必填说明
webhookIdstring是Webhook id。

返回值​

Promise<OperationSuccess>

示例​

await client.webhook.enable('wh_xxx');

refreshKey​

轮换签名密钥；旧密钥立即失效。

client.webhook.refreshKey(webhookId)

参数​

名称类型必填说明
webhookIdstring是Webhook id。

返回值​

Promise<OperationSuccess> — 成功标记在 data 中。若平台在载荷中返回新密钥，请从解析结果读取（以 TypeScript 类型与发行说明 / OpenAPI 为准）。

示例​

await client.webhook.refreshKey('wh_xxx');

remove​

client.webhook.remove(webhookId)

参数​

名称类型必填说明
webhookIdstring是Webhook id。

返回值​

Promise<OperationSuccess>

示例​

await client.webhook.remove('wh_xxx');