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

Header Name	Example Value	Description
X-Timestamp	1525872629832	Millisecond timestamp used in signature calculation
Content-Type	application/json
X-Access-No	100001	Unique access number (`access_no`) for the integrating party
X-Signature	54ea681fed566566c778a9aa1608	The signature string

Request Body Structure

Field	Type	Description	Example
id	uint64	Event id	545440011265267736
type	string	Event type	payment.success
created	string	Creation time	2025-07-01T10:25:25Z
data	object	Business object specific to the event type. The data structure varies for event types.

Event Handling Specifications

Reliability Verification

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

Extract Parameters: Obtain the X-Timestamp from the request headers (denoted as timestamp), and get the raw request body content (denoted as body).
Construct Signature Original String: Format is${timestamp}.${body}.

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

Example code: 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))
}

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

Handling Signature Verification During Key Rotation

When a key rotation is initiated, Subotiz will continue signing Webhook requests with the old key throughout the grace period. Once the old key expires, it automatically switches to the new key.

It is recommended that your endpoint support signature verification with both keys during the grace period, using the following approach:

First, compute the signature using the old key and compare it against X-Signature.
If verification fails, recompute using the new key and compare again.
If both fail, treat the request as illegitimate and reject it.

This ensures no Webhook events are lost during the key transition period.

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.