​

Signature verification

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

​

Webhook Headers

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

​

Signature Formula

​

Verification Process

1. Read the raw webhook payload
2. Extract X-SIGNATURE header
3. Extract X-TIMESTAMP header
4. Generate local HMAC SHA256 signature
5. Compare generated signature with received signature
6. 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

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

​

Expired Timestamp

• 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

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

​

Recommended Production Workflow

1. Receive webhook request
2. Read raw payload
3. Extract headers
4. Verify signature
5. Validate timestamp
6. Store webhook event
7. Verify transaction using APIs
8. Update internal systems
9. 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