Webhooks

Use the Webhook resource to register and manage HTTPS callback endpoints (URL, subscribed events, signing secret). The SDK covers management API calls only — verifying inbound webhook deliveries is your application’s responsibility (see the main API docs for signing rules).

Event types: use only supported identifiers in subscribedEvents. See Event list for all supported identifiers (same page as docs.gstable.io — event list).

Accessing webhooks

All webhook management operations are available via the client.webhook property on your GStableClient instance.

Error handling

Failures surface as GStableError or a subclass when the API returns a non-zero code or transport rules fail (for example invalid URL or permission issues).

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 support

We provide TypeScript definitions for webhook registration payloads and responses. Import them from the package root.

Core types

• Webhook — Endpoint record from create / detail (webhookId, URL, subscribedEvents, key, status, timestamps, and fields per API).
• WebhookStatus — Delivery / lifecycle status for an endpoint.

Request bodies

• CreateWebhookBody — Register a new endpoint (name, HTTPS URL, event list, optional description).
• UpdateWebhookBody — Full replacement fields including webhookId.

Response wrappers

• WebhookListData — { webhooks: Webhook[] } from list.
• OperationSuccess — Success envelope for update, enable, disable, refreshKey, remove, and similar calls.

import type {
  Webhook,
  WebhookStatus,
  CreateWebhookBody,
  UpdateWebhookBody,
  WebhookListData,
  OperationSuccess,
} from 'gstable-js';

---

create

client.webhook.create(body)

Parameters

Name	Type	Required	Description
body	CreateWebhookBody	Yes	Registration payload.

CreateWebhookBody:

Field	Type	Required	Description
webhookName	string	Yes	Display name.
webhookUrl	string	Yes	HTTPS callback URL you expose.
subscribedEvents	string[]	Yes	Event type strings — see Event list.
webhookDescription	string	No	Optional notes.

Returns

Promise<Webhook> — Includes webhookId, key (signing secret — store securely), status, timestamps.

Example

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'], // use exact names from API docs
});

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

---

update

Full replacement of webhook metadata (“full replace” semantics).

client.webhook.update(body)

Parameters

Name	Type	Required	Description
body	UpdateWebhookBody	Yes	Must include webhookId.

UpdateWebhookBody:

Field	Type	Required	Description
webhookId	string	Yes	Target endpoint.
webhookName	string	Yes	New name.
webhookUrl	string	Yes	New URL.
subscribedEvents	string[]	Yes	Replaces subscription list.
webhookDescription	string	No	Optional.

Returns

Promise<OperationSuccess>

Example

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()

Parameters

None.

Returns

Promise<WebhookListData> — { webhooks: Webhook[] } (full list for the account).

Example

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

---

detail

client.webhook.detail(webhookId)

Parameters

Name	Type	Required	Description
webhookId	string	Yes	Webhook id.

Returns

Promise<Webhook>

Example

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

---

disable

client.webhook.disable(webhookId)

Parameters

Name	Type	Required	Description
webhookId	string	Yes	Webhook id.

Returns

Promise<OperationSuccess>

Example

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

---

enable

Resumes delivery; may restore from paused state per platform rules.

client.webhook.enable(webhookId)

Parameters

Name	Type	Required	Description
webhookId	string	Yes	Webhook id.

Returns

Promise<OperationSuccess>

Example

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

---

refreshKey

Rotates signing secret; previous key is invalid immediately.

client.webhook.refreshKey(webhookId)

Parameters

Name	Type	Required	Description
webhookId	string	Yes	Webhook id.

Returns

Promise<OperationSuccess> — Success flag in data. If the platform returns a new secret in the payload, read it from the resolved value TypeScript types allow (see release notes / OpenAPI if applicable).

Example

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

---

remove

client.webhook.remove(webhookId)

Parameters

Name	Type	Required	Description
webhookId	string	Yes	Webhook id.

Returns

Promise<OperationSuccess>

Example

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