Webhook Management

Webhooks are the mechanism by which GStable pushes event notifications (such as Payment Succeeded, Settlement Completed) to your backend system in real-time. Through the Webhook API, you can manage your receiving endpoints programmatically.

Limit Note

To ensure delivery quality, each account is allowed to create a maximum of 10 Webhook endpoints.

Webhook Object

Core Attributes

Attribute	Type	Description
webhookId	String	Unique identifier for the Webhook (e.g., wkid_DDr1EN...).
webhookName	String	Name used to identify this endpoint.
webhookUrl	String	HTTPS URL receiving the POST request.
status	String	Current status. See status definitions below.
subscribedEvents	Array	List of subscribed event types (e.g., session.paid).
key	String	Signing Key. Used to verify the legitimacy of the callback notification.

Status Definitions (Status)

Status	Identifier	Description
Active	active	Normal status. The platform sends notifications to this endpoint.
Inactive	inactive	Manually disabled by user. The platform stops sending notifications.
Paused	paused	System Auto-Paused. When the platform fails to send notifications to this URL consecutively multiple times (e.g., 500 errors or timeouts), the status will be automatically set to paused. You need to fix server issues and manually restore it to active.

---

Create Webhook

POST /webhook/create

Create a new receiving endpoint. After successful creation, the system generates a unique signing key (key); please save it securely.

Request Parameters

Parameter	Type	Required	Description
webhookName	String	✅	Name (Max 100 chars).
webhookUrl	String	✅	Callback URL (Max 1000 chars). Must be HTTPS.
subscribedEvents	String[]	✅	List of subscribed events.
webhookDescription	String	❌	Description (Max 1000 chars).

Request Example

{
  "webhookName": "Production Receiver",
  "webhookUrl": "https://api.yoursite.com/webhooks/gstable",
  "webhookDescription": "Used to receive payment completion and settlement completion events",
  "subscribedEvents": [
    "session.paid",
    "session.completed"
  ]
}

Response Example

{
  "code": 0,
  "message": "success",
  "data": {
    "webhookId": "wkid_DDr1ENAGmHjPy3Oq",
    "webhookName": "Production Receiver",
    "webhookDescription": "Used to receive payment completion and settlement completion events",
    "webhookUrl": "https://api.yoursite.com/webhooks/gstable",
    "subscribedEvents": [
      "session.paid",
      "session.completed"
    ],
    "key": "wkk_example_secret_key_000",
    "createAt": "2026-01-03 08:36:03",
    "updateAt": "2026-01-03 08:36:03",
    "status": "active"
  }
}

---

Update Webhook

POST /webhook/update

Full Replacement

The update interface adopts a Full Replacement strategy. When calling this interface, you must pass all fields of the Webhook (including those you do not want to modify).

Request Example

{
  "webhookId": "wkid_DDr1ENAGmHjPy3Oq",
  "webhookName": "Production Receiver (Updated)",
  "webhookUrl": "https://api.yoursite.com/webhooks/gstable_v2",
  "webhookDescription": "Updated callback address",
  "subscribedEvents": [
    "session.paid"
  ]
}

Response Example

{
  "code": 0,
  "message": "success",
  "data": {
    "success": true
  }
}

---

Get Webhook List

GET /webhook/list

Since the platform limits each account to a maximum of 10 Webhooks, this interface returns the full list and does not provide pagination.

Response Example

{
  "code": 0,
  "message": "success",
  "data": {
    "webhooks": [
      {
        "webhookId": "wkid_DDr1ENAGmHjPy3Oq",
        "webhookName": "Test webhook",
        "webhookUrl": "https://webhook.example.com/gstable",
        "status": "active",
        "key": "wkk_example_secret_key_000",
        ...
      }
    ]
  }
}

---

Get Webhook Detail

GET /webhook/detail/:webhookId

Response Example

{
  "code": 0,
  "message": "success",
  "data": {
    "webhookId": "wkid_DDr1ENAGmHjPy3Oq",
    "webhookName": "Test Webhook-Update",
    "webhookDescription": "Used to receive payment completion and settlement completion events",
    "webhookUrl": "https://www.google.com",
    "subscribedEvents": [
      "session.paid"
    ],
    "key": "wkk_example_secret_key_000",
    "createAt": "2026-01-03 08:36:03",
    "updateAt": "2026-01-03 09:10:05",
    "status": "active"
  }
}

---

Status Management

You can manually disable or enable Webhooks. If a Webhook enters the paused state due to multiple delivery failures, you also need to restore it using the "Enable" interface.

Disable

POST /webhook/disable

Enable

POST /webhook/enable

Request Example

{
  "webhookId": "wkid_DDr1ENAGmHjPy3Oq"
}

Response Example

{
  "code": 0,
  "message": "success",
  "data": {
    "success": true
  }
}

---

Key Management

Rotate Key

POST /webhook/key/refresh

If you suspect the signing key (key) has been compromised, you can call this interface to generate a new key. Note: After rotating the key, the old key will become invalid immediately. Please ensure you update your backend verification logic synchronously, otherwise signature verification will fail.

Request Example

{
  "webhookId": "wkid_DDr1ENAGmHjPy3Oq"
}

Response Example

{
  "code": 0,
  "message": "success",
  "data": {
    "success": true
  }
}

---

Remove Webhook

POST /webhook/remove

Permanently deletes a Webhook endpoint.

Request Example

{
  "webhookId": "wkid_DDr1ENAGmHjPy3Oq"
}

Response Example

{
  "code": 0,
  "message": "success",
  "data": {
    "success": true
  }
}