> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eliteneobank.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Signature verification

> Under Development

# Signature verification

Elite Neo Bank 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:

```http theme={null}
Content-Type: application/json
X-SIGNATURE: GENERATED_SIGNATURE
X-TIMESTAMP: GENERATED_TIMESTAMP
```

## Signature Formula

Refer to:
\\

➡️ [Signature Generation](https://docs.eliteneobank.com/guide/authentication/signature.md)

## Verification Process

To verify a webhook request:

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

```text theme={null}
{
  "event": "payment.success",
  "data": {
    "order_id": "6116229263036",
    "amount": "105.00",
    "currency": "INR",
    "status": "PAID"
  }
}
```

***

**Node.js**

```javascript theme={null}
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**

```php theme={null}
<?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";
}
```

**Python**

```python theme={null}
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")
```

**Java**

```text theme={null}
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

Elite Neo Bank 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

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.