# Webhook setup

KwikPaisa Webhooks allow merchants to receive real-time payment and payout notifications directly on their server without continuously polling APIs.

Webhooks are recommended for:

* Payment status updates
* Payout status updates
* Settlement notifications
* Transaction reconciliation
* Automated workflow processing

Using webhooks helps merchants build faster, scalable, and reliable transaction systems.

***

## What are Webhooks?

A webhook is an HTTP callback sent by KwikPaisa to your server whenever a transaction event occurs.

Instead of repeatedly checking transaction status APIs, KwikPaisa automatically pushes updates to your configured webhook endpoint.

***

## Supported Webhook Events

### Payment Events

| Event                | Description                    |
| -------------------- | ------------------------------ |
| `payment.success`    | Payment completed successfully |
| `payment.failed`     | Payment failed                 |
| `payment.processing` | Payment under processing       |
| `payment.expired`    | Payment session expired        |

***

### Payout Events

| Event               | Description                   |
| ------------------- | ----------------------------- |
| `payout.success`    | Payout completed successfully |
| `payout.failed`     | Payout failed                 |
| `payout.processing` | Payout under processing       |
| `payout.reversed`   | Payout reversed               |

***

## Webhook URL Requirements

Your webhook endpoint must:

* Be publicly accessible
* Support HTTPS
* Accept `POST` requests
* Return HTTP `200 OK` quickly
* Handle JSON payloads properly

***

## Example Webhook URL

```
https://merchant.com/api/webhooks/kwikpaisa
```

## Webhook Request Method

```
POST
```

***

## Webhook Headers

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

***

## Webhook Security

Every webhook request is signed using HMAC SHA256 signature verification.

Webhook signatures should always be validated before processing webhook data.

The signature is generated using:

```
HMAC_SHA256(payload + timestamp, secret_key)
```

***

## Example Payment Webhook Payload

```
{
  "event": "payment.success",
  "data": {
    "kwikX_order_id": "kp_40dec464",
    "order_id": "6116229263036",
    "order_status": "PAID",
    "amount": "105.00",
    "currency": "INR",
    "transaction_id": "TXN938482920",
    "payment_method": "UPI",
    "created_at": "14-05-2026 12:45 PM"
  }
}
```

***

## Example Payout Webhook Payload

```
{
  "event": "payout.success",
  "data": {
    "payout_id": "payout_a782fdb71b5e1659",
    "payout_order_id": "1778761734",
    "status": "SUCCESS",
    "amount": "99",
    "currency": "INR",
    "utr_number": "UAT1778761735",
    "created_at": "14-05-2026"
  }
}
```

***

## Webhook Verification Process

Recommended verification steps:

1. Read webhook payload
2. Extract `X-SIGNATURE` header
3. Extract `X-TIMESTAMP` header
4. Generate local signature
5. Compare generated signature with received signature
6. Process webhook only if signatures match

***

## Example Node.js Verification

```
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');
} else {
  console.log('Invalid webhook signature');
}
```

***

## Webhook Response Requirements

Your server should return:

```
HTTP 200 OK
```

immediately after successful webhook processing.

***

## Retry Mechanism

If your server:

* Times out
* Returns non-200 responses
* Fails to respond

KwikPaisa may retry webhook delivery automatically.

***

## Recommended Retry Handling

Your webhook system should:

* Handle duplicate events safely
* Store webhook logs
* Use idempotent processing
* Verify transaction status using APIs when needed

***

## Best Practices

* Always validate webhook signatures
* Use HTTPS endpoints only
* Respond quickly with HTTP 200
* Process webhook logic asynchronously
* Store webhook payloads for audit logs
* Verify final transaction status server-side

***

## Important Notes

* Webhooks should not be trusted without verification
* Duplicate webhook events may occur
* Payment status should always be verified server-side
* Webhooks complement APIs and do not replace verification APIs

***

## Common Errors

### Invalid Signature

Possible reasons:

* Incorrect secret key
* Payload modification
* Timestamp mismatch

***

### Webhook Timeout

Possible reasons:

* Slow webhook processing
* Server downtime
* Network failures

***

## Recommended Production Workflow

1. Receive webhook
2. Verify signature
3. Validate payload
4. Store webhook event
5. Verify transaction status using APIs
6. Update merchant system
7. Return HTTP 200 response


---

# 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/webhook-setup.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.