Signature verification

Under Development

KwikPaisa signs every webhook request using HMAC SHA256 to ensure webhook authenticity and payload integrity.

Webhook signature verification helps merchants:

Verify webhook authenticity
Prevent unauthorized requests
Detect payload tampering
Protect webhook endpoints against replay attacks

All webhook requests should always be verified before processing transaction data.

Webhook Headers

Every webhook request contains:

Content-Type: application/json
X-SIGNATURE: GENERATED_SIGNATURE
X-TIMESTAMP: GENERATED_TIMESTAMP

Signature Formula

Refer to: \

➡️ Signature Generation

Verification Process

To verify a webhook request:

Read the raw webhook payload
Extract X-SIGNATURE header
Extract X-TIMESTAMP header
Generate local HMAC SHA256 signature
Compare generated signature with received signature
Process webhook only if signatures match

Important Rules

Use the raw request payload exactly as received
Do not modify JSON formatting before verification
Verify timestamps to prevent replay attacks
Reject invalid signatures immediately
Always use your server-side secret_key

Example Webhook Payload

{
  "event": "payment.success",
  "data": {
    "order_id": "6116229263036",
    "amount": "105.00",
    "currency": "INR",
    "status": "PAID"
  }
}

const crypto = require('crypto');
const payload = JSON.stringify(req.body);
const timestamp = req.headers['x-timestamp'];
const receivedSignature = req.headers['x-signature'];
const generatedSignature = crypto
  .createHmac('sha256', 'YOUR_SECRET_KEY')
  .update(payload + timestamp)
  .digest('hex');
if (generatedSignature === receivedSignature) {
  console.log('Webhook verified successfully');
} else {
  console.log('Invalid webhook signature');
}

<?php
$payload = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_TIMESTAMP'];
$receivedSignature = $_SERVER['HTTP_X_SIGNATURE'];
$generatedSignature = hash_hmac(
    'sha256',
    $payload . $timestamp,
    'YOUR_SECRET_KEY'
);
if ($generatedSignature === $receivedSignature) {
    echo "Webhook verified successfully";
} else {
    echo "Invalid webhook signature";
}

import hmac
import hashlib
payload = request.data.decode()
timestamp = request.headers.get('X-TIMESTAMP')
received_signature = request.headers.get('X-SIGNATURE')
generated_signature = hmac.new(
    b'YOUR_SECRET_KEY',
    (payload + timestamp).encode(),
    hashlib.sha256
).hexdigest()
if generated_signature == received_signature:
    print("Webhook verified successfully")
else:
    print("Invalid webhook signature")

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
String payload = requestBody;
String timestamp = request.getHeader("X-TIMESTAMP");
String receivedSignature = request.getHeader("X-SIGNATURE");
String data = payload + timestamp;
Mac sha256Hmac = Mac.getInstance("HmacSHA256");
SecretKeySpec secretKey = new SecretKeySpec(
    "YOUR_SECRET_KEY".getBytes(),
    "HmacSHA256"
);
sha256Hmac.init(secretKey);
byte[] hash = sha256Hmac.doFinal(data.getBytes());
StringBuilder generatedSignature = new StringBuilder();
for (byte b : hash) {
    generatedSignature.append(
        String.format("%02x", b)
    );
}
if (generatedSignature.toString().equals(receivedSignature)) {
    System.out.println("Webhook verified successfully");
} else {
    System.out.println("Invalid webhook signature");
}

Common Verification Failures

Invalid Signature

Possible reasons:

Incorrect secret key
Modified payload
Incorrect JSON formatting
Wrong timestamp
Incorrect signature generation logic

Expired Timestamp

Possible reasons:

Delayed webhook processing
System time mismatch
Replay attack prevention triggered

Security Recommendations

Always verify webhook signatures
Use HTTPS webhook endpoints only
Reject invalid requests immediately
Store webhook logs securely
Verify timestamps before processing
Never expose secret keys publicly

Replay Attack Protection

KwikPaisa includes timestamps in webhook requests to prevent replay attacks.

Replay attacks occur when attackers resend previously valid webhook payloads maliciously.

To prevent replay attacks:

Validate timestamps
Reject old requests
Store processed webhook event IDs
Implement idempotent processing

Recommended Production Workflow

Receive webhook request
Read raw payload
Extract headers
Verify signature
Validate timestamp
Store webhook event
Verify transaction using APIs
Update internal systems
Return HTTP 200 response

Best Practices

Process webhooks asynchronously
Avoid long-running webhook responses
Return HTTP 200 quickly
Verify payment/payout status using APIs
Maintain webhook audit logs

PreviousWebhook setup NextTest credentials

Last updated 2 months ago