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

# Webhook setup

# Webhook setup

Elite Neo Bank 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 Elite Neo Bank to your server whenever a transaction event occurs.

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

***

## Supported Webhook Events

**PG Orders Events**

| Event | Description |
| - | - |
| `pg.order.created` | Order created successfully |
| `pg.order.updated` | Order details updated |
| `pg.order.pending` | Order awaiting payment |
| `pg.order.processing` | Order is being processed |
| `pg.order.completed` | Order completed successfully |
| `pg.order.failed` | Order processing failed |
| `pg.order.cancelled` | Order cancelled |
| `pg.order.expired` | Order session expired |
| `pg.order.closed` | Order closed |
| `pg.order.refund_initiated` | Refund initiated for order |
| `pg.order.refunded` | Order refunded successfully |
| `pg.order.partially_refunded` | Partial refund processed for order |
| `pg.order.dispute.created` | Dispute created for order |
| `pg.order.dispute.closed` | Order dispute resolved/closed |
| `pg.order.chargeback.created` | Chargeback initiated for order |
| `pg.order.payment.success` | Payment received for order |
| `pg.order.payment.failed` | Payment attempt failed for order |
| `pg.order.webhook.failed` | Order webhook delivery failed |
| `pg.order.webhook.retrying` | Retrying failed order webhook delivery |

**PG Payments Events**

| Event | Description |
| - | - |
| `pg.payment.created` | Payment order created |
| `pg.payment.pending` | Payment pending from customer |
| `pg.payment.processing` | Payment is being processed |
| `pg.payment.success` | Payment completed successfully |
| `pg.payment.failed` | Payment failed |
| `pg.payment.cancelled` | Payment cancelled |
| `pg.payment.expired` | Payment session expired |
| `pg.payment.refunded` | Full refund processed |
| `pg.payment.partially_refunded` | Partial refund processed |
| `pg.refund.created` | Refund request created |
| `pg.refund.processing` | Refund under processing |
| `pg.refund.success` | Refund completed successfully |
| `pg.refund.failed` | Refund failed |
| `pg.settlement.created` | Settlement generated |
| `pg.settlement.processed` | Settlement processed successfully |
| `pg.settlement.failed` | Settlement processing failed |
| `pg.dispute.created` | Payment dispute created |
| `pg.dispute.updated` | Dispute details updated |
| `pg.dispute.won` | Dispute resolved in merchant favor |
| `pg.dispute.lost` | Dispute lost |
| `pg.dispute.closed` | Dispute closed |
| `pg.dispute.fee.withdrawal` | Dispute handling fee deducted |
| `pg.dispute.fee.refunded` | Dispute fee refunded |
| `pg.chargeback.created` | Chargeback initiated |
| `pg.chargeback.processing` | Chargeback under review |
| `pg.chargeback.won` | Chargeback resolved in merchant favor |
| `pg.chargeback.lost` | Chargeback lost |
| `pg.chargeback.closed` | Chargeback closed |
| `pg.withdrawal.created` | Wallet withdrawal initiated |
| `pg.withdrawal.processing` | Withdrawal under processing |
| `pg.withdrawal.success` | Withdrawal completed successfully |
| `pg.withdrawal.failed` | Withdrawal failed |
| `pg.webhook.failed` | Webhook delivery failed |
| `pg.webhook.retrying` | Webhook retry attempt in progress |

**Payout Events**

| Event | Description |
| - | - |
| `po.payout.created` | Payout request created |
| `po.payout.queued` | Payout added to processing queue |
| `po.payout.processing` | Payout is being processed |
| `po.payout.success` | Payout completed successfully |
| `po.payout.failed` | Payout failed |
| `po.payout.reversed` | Payout reversed back to wallet |
| `po.payout.cancelled` | Payout cancelled |
| `po.payout.refunded` | Payout amount refunded |
| `po.payout.pending` | Payout pending approval or processing |
| `po.payout.on_hold` | Payout temporarily placed on hold |
| `po.payout.bank_rejected` | Bank rejected payout request |
| `po.payout.bank_processing` | Bank is processing payout |
| `po.payout.retrying` | Payout retry attempt initiated |
| `po.payout.timeout` | Payout processing timed out |
| `po.payout.webhook.failed` | Payout webhook delivery failed |
| `po.payout.webhook.retrying` | Retrying failed payout webhook delivery |

***

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

```text theme={null}
https://merchant.com/api/webhooks/Elite Neo Bank
```

## Webhook Request Method

```text theme={null}
POST
```

***

## Webhook Headers `UNDER DEVELOPMENT`

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

***

## Webhook Security `UNDER DEVELOPMENT`

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:

```text theme={null}
HMAC_SHA256(payload + timestamp, secret_key)
```

***

## Example Payment Webhook Payload

```json theme={null}
{
  "event": "pg.payment.success",
  "code": 200,
  "status": true,
  "message": "API authentication successful!",
  "data": {
    "kwikX_order_id": "kp_9b9e725b-b415-40fd-ac1c-068ab508f7e7",
    "order_id": "6873654104683",
    "payment_id": "pay_dgfdggdgdfg",
    "order_amount": "105.00",
    "order_currency": "INR",
    "order_status": "PAID",
    "order_source": "API",
    "created_at": null,
    "paymentDetails": {}
  }
}
```

***

## Example Payout Webhook Payload

```json theme={null}
{
  "event": "po.payout.success",
  "data": {
    "order_id": "1778761734",
    "kwikx_payout_id": "payout_a782fdb71b5e1659",
    "status": "SUCCESS",
    "amount": "99",
    "currency": "INR",
    "utr_number": "UAT1778761735",
    "txnLog": {
      "account_transfer": {
        "account_number": "6760654654",
        "account_owner_name": "beneficiary name",
        "ifsc_code": "icici000143",
        "is_validate": "false",
        "payment_for": "salary payment"
      },
      "address": null,
      "beneficiary_id": null,
      "country_dialing_code": "91",
      "debit_account_type": "kwikx_wallet",
      "email": "email@example.com",
      "kwikx_wallet_id": "2026-04-30 13:01:32",
      "mobile": "9896989698",
      "payout_order_id": 1778761734,
      "transfer_amount": "99",
      "transfer_mode": "imps",
      "transfer_type": "direct",
      "api_user_id": 472,
      "business_profile_id": 96,
      "api_key_id": 8,
      "mode": "sandbox"
    },
    "processed_at": "2026-05-14 12:28:55"
  }
}
```

***

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

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

***

## Webhook Response Requirements

Your server should return:

```text theme={null}
HTTP 200 OK
```

immediately after successful webhook processing.

***

## Retry Mechanism

If your server:

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

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


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