Skip to main content

Webhook Configuration

After completing the backend code integration, you need to configure a receiving address in the GStable merchant dashboard so that the platform can push payment results to your server.

Configure Receiving Endpoint​

The merchant dashboard supports configuring up to 10 independent Webhook endpoints. You can distribute events to different URLs based on environments (Development/Production) or business modules.

Steps to Add​

  1. Log in to the merchant dashboard, go to "Webhook" page.
  2. Click "+ Add Endpoint".
  3. Fill Configuration Info:
    • Endpoint URL: The interface address your server uses to receive POST requests (e.g., https://api.yoursite.com/webhook/gstable). Must start with https://.
    • Subscribe Events: Check the event types you care about as needed. Usually, subscribing to session.paid and session.completed is sufficient.

Get Signing Secret​

To ensure security, GStable assigns an independent key to each Webhook endpoint for generating request signatures.

  1. Click the endpoint you just created in the Webhook list.
  2. In the "Signing Secret" area of the details page, click "Click to Reveal".
  3. You will see a string starting with wkk_.
    • Note: Please keep this key safe and do not expose it in frontend code.

Security Verification Mechanism​

When your server receives a request, it must perform signature verification to prevent man-in-the-middle attacks or forged requests.

Verification Principle​

GStable request headers contain the following key fields:

  • x-gstable-timestamp: Request sent timestamp.
  • x-gstable-signature: Signature generated based on HMAC-SHA256 algorithm.

Signature Construction Rule:

SignedPayload = Timestamp + ":" + RawBody

Quick Verification Example (Node.js)​

Here is a simplified verification function. For more detailed implementation, please refer to the API documentation.

const crypto = require('crypto');

// Key starting with wkk_ obtained from Dashboard
const WEBHOOK_SECRET = 'wkk_...';

function verifySignature(req) {
  const signature = req.headers['x-gstable-signature'];
  const timestamp = req.headers['x-gstable-timestamp'];
  const rawBody = JSON.stringify(req.body); // Suggest getting raw Buffer in production

  // 1. Construct string to sign
  const payload = `${timestamp}:${rawBody}`;

  // 2. Calculate signature
  const expectedSignature = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');

  // 3. Compare
  if (signature === expectedSignature) {
    return true;
  }
  return false;
}
Dive Deeper

For detailed verification steps, replay attack prevention, and complete code implementation, please consult API Reference: Verification & Handling.

Retry Strategy​

If your server fails to respond correctly (i.e., returns a status code other than 2xx), or the request times out (over 10 seconds), GStable will consider the delivery failed.

The system automatically executes a retry mechanism:

  • Strategy: Exponential Backoff.
  • Frequency: Retry intervals will gradually lengthen (e.g., 1 minute, 5 minutes, 30 minutes...).
  • Duration: The system will continue trying within 24 hours; if it still fails, it will stop pushing that event.
Avoid Timeout

Please ensure your Webhook processing logic is as fast as possible. If business logic (such as shipping, database operations) takes a long time, it is recommended to return 200 OK first, then process the business asynchronously in the background.

Webhook event list →