# Signature verification

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:

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

## Signature Formula

Refer to: \\

➡️ [Signature Generation](/v3-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

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

***

{% tabs %}
{% tab title="Node.js" %}

```javascript
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');
}
```

{% endtab %}

{% tab title="PHP" %}

```php
<?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";
}
```

{% endtab %}

{% tab title="Python" %}

```python
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")
```

{% endtab %}

{% tab title="Java" %}

```
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");
}
```

{% endtab %}
{% endtabs %}

## 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

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.kwikpaisa.com/v3-guide/webhooks/signature-verification.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.