When integrating with the Subotiz system, merchants can configure a Webhook notification endpoint to receive account-related events in real-time. This enables the backend system to trigger corresponding business logic processing (such as payment status updates, subscription status changes, etc.).

​​Notification Principle:​​

When specific events are triggered within the Subotiz system, an HTTPS POST request will be sent to the configured Webhook endpoint. The request contains the following key elements:

• ​​Request Payload​​: A structured event object compliant with JSON format specifications, containing the event identifier, type, and specific business data.
• ​​Request Headers​​: Include specific headers used for authentication and request identification (e.g., X-Timestamp, X-Signature).

Request Composition

Request Headers

Request Body Structure

Event Handling Specifications

Reliability Verification

Before processing an event, verify the legitimacy of the request through the following steps:

1. ​​Extract Parameters​​: Obtain the X-Timestamp from the request headers (denoted as timestamp), and get the raw request body content (denoted as body).

2. Construct Signature Original String​​: Format is${timestamp}.${body}.

3. Calculate Signature: Using the access_secret assigned by Subotiz as the secret key, compute the signature value via the HMAC-SHA256 algorithm.

   1. Example code: GO
   2. Go

      // Calculate Signature
      func CalcSignature(timestamp int64, body []byte, secret string) string {
          mac := hmac.New(sha256.New, []byte(secret))
          mac.Write([]byte(fmt.Sprintf("%d", timestamp)))
          mac.Write([]byte("."))
          mac.Write(body)
          return hex.EncodeToString(mac.Sum(nil))
      }

4. ​​Compare and Verify​​: Compare the calculated signature with the X-Signature value from the request headers. If they match, the request is legitimate.

Processing Requirements

• ​​Idempotency​​: Implement idempotent processing for duplicate events based on the unique event id to avoid duplicate operations.
• ​​Event Filtering​​: Identify relevant event types based on the typefield. Return an HTTP 200 status code directly for non-relevant types.
• ​​Order Independence​​: The system does not guarantee the order of events. For critical business processes, actively query the latest status via API to synchronize.

Response and Retry Mechanism

• ​​Successful Response​​: Return an HTTP 200 status code upon successful event processing to indicate successful handling.
• ​​Failure and Retry​​: If a non-200 status code is returned or a timeout occurs, the system will perform retries with backoff within 48 hours, up to 16 times. The initial interval is 1 minute, doubling each time (e.g., 1m, 2m, 4m, ...), with a maximum interval cap of 4 hours between retries.