Webhooks & Payload Security

Webhooks are real-time HTTP POST notifications triggered by financial events. In V2, Servinux uses an atomic notification system to ensure your system and merchant balances are updated instantly when transactions are finalized.

Security & Signature Verification

To prevent spoofing, Servinux signs every webhook payload with an x-servinux-signature header. You must verify this HMAC SHA512 hash using your Secret Key.

Capture exact raw bytes using php://input. Do not re-encode JSON before hashing.

Compute HMAC SHA512 using your Secret Key and the raw body.

Compare the computed hash to the header using hash_equals().

Implementation Handler (PHP)

webhook_handler.php

// 1. Capture the absolute raw payload (Required for signature accuracy)
$payload = file_get_contents("php://input");
$headers = array_change_key_case(getallheaders(), CASE_LOWER);
$signature = $headers['x-servinux-signature'] ?? '';

// 2. Validate Signature using your Secret Key
$expected = hash_hmac('sha512', $payload, "YOUR_SECRET_KEY");

if (!hash_equals($expected, $signature)) {
    http_response_code(401); 
    exit("Invalid Signature");
}

// 3. Process Verified Data
$data = json_decode($payload, true);
$status = strtoupper($data['transaction_status'] ?? '');

if ($status === 'SUCCESS') {
    // 4. Implement Idempotency Check (transaction_reference)
    // 5. Atomic logic to credit your internal wallet/service
}

// 6. Response with 200 OK
http_response_code(200);
echo json_encode(["status" => "processed"]);

Sample SUCCESS Payload

JSON EVENT

{
  "virtual_account_number": "9008987340",
  "customer_identifier": "9B_VA_21_EXT",
  "amount_received": 5000.00,
  "transaction_status": "SUCCESS",
  "transaction_reference": "SERV_TXN_948487217",
  "email": "[email protected]",
  "date": "2026-02-25T10:40:00.000Z"
}

Reliability & Idempotency

If your server fails to respond with a 200 OK, Servinux will retry delivery using an exponential backoff strategy. You must use the transaction_reference to implement idempotency checks and prevent double-crediting.