Webhooks

To configure your webhook URL please refer to the Webhook Configuration guide.

Webhook Validation

Each webhook request will include the following headers for validation:

{
  "X-TIMESTAMP": 1752670745,
  "X-SIGNATURE": "ohmVyfuNup6eKWOdOZBBZut5CMPdPTfFSB/zDT/eXQo="
}

X-TIMESTAMP: Unix timestamp when the webhook was generated.
X-SIGNATURE: HMAC-SHA256 signature, Base64 encoded. You should verify every incoming webhook by validating the signature using your api_key & api_secret. Below is a sample Python code snippet for generating and verifying webhook signatures:

import base64
import hmac
import hashlib
import time
import json

def generate_hmac_signature(api_key, api_secret, timestamp, body={}):
    """Generates HMAC signature"""
    # sort the body
    body = json.dumps(body, sort_keys=True, separators=(",", ":"))
    message = f"{api_key}|{timestamp}|{body}".encode()
    print("message to sign", message)
    signature = hmac.new(api_secret.encode(), message, hashlib.sha256).digest()
    return base64.b64encode(signature).decode()

def verify_hmac_signature(api_key, timestamp, signature, body, api_secret):
    """Verify API key and HMAC signature"""
    expected_signature = generate_hmac_signature(api_key, api_secret, timestamp, body)
    print(expected_signature)
    if not hmac.compare_digest(expected_signature, signature): return False
    return True

Usage Example:

is_valid = verify_hmac_signature(
    api_key="your_api_key",
    api_secret="your_api_secret",
    timestamp=received_timestamp,
    signature=received_signature,
    body=webhook_body_dict,
)
if not is_valid:
    # Reject the webhook
    ...

Always verify the signature and timestamp before processing any webhook data.

Webhook Structure

All webhook notifications follow this consistent structure:

{
  "type": "string", // The entity type (e.g., "PAYOUT", "PAYIN", "CUSTOMER", "BANK", "EDD")
  "id": "string", // Unique ID of the entity
  "event": "string", // The state change event
  "timestamp": "timestamp",
  "metadata": {
    "failure_reason": "string" // In case of FAILED event
  }
}

Metadata Fields

The metadata object in webhook payloads contains additional context-specific information based on the event type and state. Below are the potential fields that may appear in metadata:

Payin Events

failure_reason (string): Present when the payin event is FAILED. Contains the specific reason for the failure (e.g., INCORRECT_UTR, PAYMENT_NOT_RECEIVED etc). See Failure Reason Reference for all possible values.
refund_reason (string): Present when the payin event is REFUND_INITIATED or REFUNDED. Contains the reason why the refund was initiated. Possible values include: INCORRECT_AMOUNT, PAYMENT_FROM_NON_WHITELISTED_ACCOUNT, THIRD_PARTY_PAYMENT. See Failure Reason Reference for all possible values.

Customer Events

failure_reason (string): Present when the customer event is FAILED. Contains the specific reason for KYC verification failure (e.g., DOCUMENT_VERIFICATION_FAILED, TAX_VERIFICATION_FAILED, KYC_FAILED). See Failure Reason Reference for all possible values.

Bank Events

failure_reason (string): Present when the bank event is FAILED. Contains the specific reason for bank verification failure (e.g., ACCOUNT_TYPE_NRE, PENNY_DROP_FAILED, NAME_MISMATCH, BANK_RISK_CHECK_FAILED etc). See Failure Reason Reference for all possible values.

Metadata fields are only included when relevant to the event. For successful events or events without additional context, the metadata object may be empty {}.

Webhook Events

Customer Events

Customer webhooks are triggered when a customer's verification status changes. Below are the possible customer states:

Event	Description
`VERIFIED`	Customer has completed KYC verification
`FAILED`	Customer verification failed or account suspended

Example customer webhook payload:

{
  "type": "CUSTOMER",
  "event": "FAILED",
  "id": "12348400-e29b-41d4-a716-446655440000",
  "timestamp": "2024-03-13T10:00:00Z",
  "metadata": {
    "failure_reason": "TAX_VERIFICATION_FAILED"
  }
}

Bank Events

Bank webhooks are triggered when a customer's bank account details or UPI ID is verified. Below are the possible states:

Event	Description
`VERIFIED`	Bank Account or UPI ID is verified successfully and can be used to place orders
`FAILED`	Bank Account or UPI ID verification failed and the bank account cannot be used to place orders

Example bank webhook payloads:

VERIFIED event:

{
  "type": "BANK",
  "event": "VERIFIED",
  "id": "12348400-e29b-41d4-a716-446655440000",
  "timestamp": "2024-03-13T10:00:00Z",
  "metadata": {}
}

FAILED event:

{
  "type": "BANK",
  "event": "FAILED",
  "id": "12348400-e29b-41d4-a716-446655440000",
  "timestamp": "2024-03-13T10:00:00Z",
  "metadata": {
    "failure_reason": "BANK_RISK_CHECK_FAILED"
  }
}

Payout Events

Payout webhooks are triggered when the status of a payout changes. Below are the possible payout states:

Event	Description
`SUCCESS`	The payout has been successfully completed
`FAILED`	The payout has failed (e.g., AML Screening failed)
`REFUNDED`	The payout amount has been reversed
`CANCELLED`	The payout has been cancelled

Example payout webhook payload:

{
  "type": "PAYOUT",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "SUCCESS",
  "timestamp": "2024-03-13T10:00:00Z",
  "metadata": {
    "utr": "RATN12341234XYZ"
  }
}

Payin Events

Payin webhooks are triggered when the status of a payin changes. Below are the possible payin states:

Event	Description
`SUCCESS`	The payin has been successfully completed
`FAILED`	The payin has failed (e.g., AML Screening failed)
`REFUND_INITIATED`	The refund has been initiated for this payin
`REFUNDED`	The payin amount has been reversed
`ON_HOLD`	The payin is put on hold

Example payin webhook payloads:

SUCCESS event:

{
  "type": "PAYIN",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "SUCCESS",
  "timestamp": "2024-03-13T10:00:00Z",
  "metadata": {}
}

FAILED event:

{
  "type": "PAYIN",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "FAILED",
  "timestamp": "2024-03-13T10:00:00Z",
  "metadata": {
    "failure_reason": "INCORRECT_UTR"
  }
}

REFUND_INITIATED event:

{
  "type": "PAYIN",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "REFUND_INITIATED",
  "timestamp": "2024-03-13T10:00:00Z",
  "metadata": {
    "refund_reason": "INCORRECT_AMOUNT"
  }
}

REFUNDED event:

{
  "type": "PAYIN",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "REFUNDED",
  "timestamp": "2024-03-13T10:00:00Z",
  "metadata": {
    "refund_reason": "THIRD_PARTY_PAYMENT"
  }
}

EDD Events

EDD webhooks are triggered when a customer's enhanced due diligence verification status changes. Below are the possible states:

Event	Description
`VERIFIED`	Customer's EDD is verified successfully and customer will now have enhanced onramp limits
`FAILED`	Customer's EDD verification failed. The payin limits will remain unchanged

Example EDD webhook payload:

{
  "type": "EDD",
  "event": "VERIFIED",
  "id": "12348400-e29b-41d4-a716-446655440000",
  "timestamp": "2024-03-13T10:00:00Z",
  "metadata": {}
}