Help Center
VCCHUB How-to
  1. Issuing
  • Guides
    • Welcome
    • Interface
  • API Reference
    • Introduction
    • Endpoints
    • Data Types
    • Signing
    • 3-D Secure Verification
    • Subscription
    • Errors
    • Webhooks
    • Items Information
    • Changelog
    • Acquiring
      • Create a direct payment
        POST
      • Create a APM payment
        POST
      • Create a redirect (iFrame) payment
        POST
      • Query a transaction
        POST
      • Capture a transaction
        POST
      • Review a transaction
        POST
      • Cancel a transaction
        POST
      • Cancel a subscription
        POST
      • Refund a transaction
        POST
      • Search a refund transaction
        POST
      • Create a payout
        POST
      • Optimise payment methods
        POST
      • Batch Upload Logistics Information
        POST
      • Query a payout transaction
        POST
      • Query Merchant Payout Balance
        POST
      • Query Merchant Unsettled Amount
        POST
    • Issuing
      • Webhook Signature Verification
      • Cardholder
        • Create cardholder
        • Update Cardholder
        • Delete cardholder
        • Query cardholder
      • Group
        • Create group
        • Query group details
        • Delete group
        • Group Card Withdrawal
        • Update group status
        • Recharge group
        • Query rule
      • Card
        • Create a card
        • Query card details
        • Query card transaction
        • Cancel a card
        • Withdraw from a card
        • Update card status
        • Recharge card
        • Update shared card limit
        • Query for card operation
        • Query card BIN
      • Account
        • Query Account Balance
  • Appendix
    • Test Cards
    • Bank Code
    • Country Code
    • Currency Code
    • Payment Methods
  1. Issuing

Webhook Signature Verification

1. Overview#

The Issuing webhook signature mechanism has been upgraded from the legacy merchant SIGN_KEY-based signature to timestamp-based HMAC-SHA256 verification using the API Key.
This is a mandatory migration. Merchants must implement and deploy the new webhook signature verification mechanism before the migration deadline communicated directly by Star SaaS.
After the migration deadline, Star SaaS will no longer send webhooks using the legacy signature format.
This page applies to Issuing webhooks only. Paygate Acquiring webhook behavior and signature rules remain unchanged.

2. Webhook Request Headers#

HeaderDescription
company_idMerchant ID.
X-Vcc-DateUnix timestamp in seconds when the signature was generated.
X-Vcc-SignatureSignature header in the format t={timestamp},v1={signature}. The timestamp t must match X-Vcc-Date.

Example#

These placeholders illustrate the header format only. Generate a current Unix timestamp and calculate the signature for the exact request body for each notification; do not reuse placeholder values.
The timestamp format for outbound webhook notifications differs from the ISO-8601 timestamp used in inbound Issuing API requests.

3. Signature Calculation#

expected = hexLower(HMAC-SHA256(apiKey, t + "." + body))
Where apiKey is the original API Key for the applicable environment, t is the Unix timestamp in seconds, and body is the original request body exactly as received.
The API Key is a 64-character hexadecimal string. For HMAC calculation, use the UTF-8 bytes of the original string directly as the key. Do not decode the hexadecimal string into 32 binary bytes.

4. Verification Steps#

1.
Read the raw request body exactly as received. Do not deserialize and reserialize the JSON before signature verification.
2.
Validate X-Vcc-Date as a numeric Unix timestamp in seconds. Reject missing values, non-numeric values, millisecond timestamps, and ISO-8601 timestamps.
3.
Parse t and v1 from X-Vcc-Signature. Validate t and ensure its numeric value exactly matches X-Vcc-Date.
4.
Verify that the timestamp is within ±300 seconds of the current server time. Reject notifications outside this window.
5.
Recalculate expected = hexLower(HMAC-SHA256(apiKey, t + "." + body)) using the original request body.
6.
Compare the calculated signature with v1 using a constant-time comparison. Accept the signature only if the values match.
7.
After successful verification, process the notification and implement idempotency based on the business transaction or notification identifier.
If any validation step fails, reject the notification and do not execute the associated business operation.

5. Java Verification Example#

The HMAC key must be the original API Key string encoded as UTF-8 bytes. Do not decode the hexadecimal string into 32 binary bytes.
The example verifies all required conditions: a valid Unix timestamp in seconds, matching timestamps in both headers, a valid timestamp window, and a matching HMAC signature. Reject the notification if any condition fails.

6. Migration Requirements#

Merchants must deploy the new webhook signature verification logic before the migration deadline communicated directly by Star SaaS.
After the migration deadline, Star SaaS will send only the new webhook signature format.
Legacy webhook signature notifications will no longer be sent.
The platform does not provide per-merchant gradual switching or long-term coexistence of legacy and new formats.
Previous
Query Merchant Unsettled Amount
Next
Create cardholder