Webhooks Guide

Webhooks allow you to receive real-time HTTP notifications when verification requests complete. Instead of polling for results, your server receives automatic updates as soon as processing finishes.

How Webhooks Work

Submit Request

You submit a verification request (e.g., UPI by Mobile)

Request Queued

API returns 202 Accepted with a request ID

Processing

TxnCheck processes the verification request

Webhook Delivered

Results are sent to your configured webhook URL

Confirmation

Your server returns 2xx to acknowledge receipt

Setting Up Webhooks

Webhook URLs are configured at the merchant account level. Contact your account manager or configure webhooks in the Merchant Dashboard under Settings → Webhooks.

Requirements

HTTPS URL - Webhook endpoints must use HTTPS
Public accessibility - Your endpoint must be reachable from the internet
Quick response - Return 2xx within 30 seconds

Webhook Events

Event	Description
`request.completed`	Verification completed successfully
`request.failed`	Verification failed
`request.partial`	Verification partially completed (some steps failed)

Webhook Payload

All webhook payloads follow this structure:

{
  "event": "request.completed",
  "timestamp": "2025-01-11T10:30:00.000Z",
  "data": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "method": "upi-by-mobile",
    "status": "COMPLETED",
    "result": {
      "name": "JOHN DOE",
      "upi": [
        "johndoe@upi",
        "9876543210@paytm"
      ],
      "status": "1"
    },
    "completedAt": "2025-01-11T10:30:00.000Z"
  }
}

Payload Fields

Field	Type	Description
`event`	string	Event type (`request.completed`, `request.failed`, `request.partial`)
`timestamp`	string	ISO 8601 timestamp when webhook was generated
`data.requestId`	string	Unique request identifier
`data.method`	string	Verification method used
`data.status`	string	Final request status
`data.result`	object	Verification result data (if successful)
`data.error`	object	Error details (if failed)
`data.stepStatuses`	object	Individual step statuses (for full-check)
`data.completedAt`	string	When the request completed

Full Check Step Statuses

For full-check requests, the stepStatuses field shows the outcome of each verification step:

{
  "event": "request.completed",
  "timestamp": "2025-01-11T10:30:00.000Z",
  "data": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "method": "full-check",
    "status": "COMPLETED",
    "stepStatuses": {
      "upiByMobile": "ok",
      "kycByMobile": "ok",
      "vpaChargebackCheck": "ok"
    },
    "result": {
      "upiByMobile": {
        "name": "JOHN DOE",
        "vpas": ["johndoe@upi", "9876543210@paytm"],
        "status": "1"
      },
      "kycByMobile": {
        "fullName": "JOHN DOE",
        "pan": "ABCDE1234F",
        "maskedAadhaar": "XXXXXXXX1234",
        "dob": "1990-01-15",
        "status": "1",
        "cached": false
      },
      "vpaChargebackCheck": {
        "vpas": [
          { "vpa": "johndoe@upi", "isBlocklisted": false },
          { "vpa": "9876543210@paytm", "isBlocklisted": false }
        ]
      }
    },
    "completedAt": "2025-01-11T10:30:00.000Z"
  }
}

Use result.vpaChargebackCheck.vpas[].isBlocklisted to determine blocklist status.

Webhook Headers

Each webhook request includes these headers:

Header	Description
`Content-Type`	Always `application/json`
`X-Webhook-Timestamp`	Unix timestamp (milliseconds) when signature was created
`X-Webhook-Signature`	HMAC-SHA256 signature for verification

Signature Verification

Always verify webhook signatures to ensure requests are from TxnCheck and haven’t been tampered with.

Verification Algorithm

payload_to_sign = `${timestamp}.${JSON.stringify(body)}`
expected_signature = HMAC_SHA256(webhook_secret, payload_to_sign)

Implementation Examples

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, timestamp, secret) {
  // Reject old timestamps (> 5 minutes)
  const currentTime = Date.now();
  if (Math.abs(currentTime - parseInt(timestamp)) > 300000) {
    throw new Error('Timestamp too old');
  }

  // Calculate expected signature
  const payloadToSign = `${timestamp}.${JSON.stringify(payload)}`;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payloadToSign)
    .digest('hex');

  // Compare signatures using timing-safe comparison
  if (!crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  )) {
    throw new Error('Invalid signature');
  }

  return true;
}

// Express.js example
app.post('/webhooks/txncheck', express.json(), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const timestamp = req.headers['x-webhook-timestamp'];
  
  try {
    verifyWebhookSignature(req.body, signature, timestamp, WEBHOOK_SECRET);
    
    const { event, data } = req.body;
    console.log(`Received ${event} for request ${data.requestId}`);
    
    switch (event) {
      case 'request.completed':
        // Process successful verification
        handleVerificationComplete(data);
        break;
      case 'request.failed':
        // Handle failed verification
        handleVerificationFailed(data);
        break;
      case 'request.partial':
        // Handle partial completion
        handlePartialVerification(data);
        break;
    }
    
    res.status(200).json({ received: true });
  } catch (error) {
    console.error('Webhook error:', error.message);
    res.status(400).json({ error: error.message });
  }
});

import hmac
import hashlib
import time
import json
from flask import Flask, request, jsonify

app = Flask(__name__)
WEBHOOK_SECRET = 'your_webhook_secret'

def verify_webhook_signature(payload, signature, timestamp, secret):
    # Reject old timestamps (> 5 minutes)
    current_time = int(time.time() * 1000)
    if abs(current_time - int(timestamp)) > 300000:
        raise ValueError('Timestamp too old')
    
    # Calculate expected signature
    payload_to_sign = f"{timestamp}.{json.dumps(payload, separators=(',', ':'))}"
    expected_signature = hmac.new(
        secret.encode(),
        payload_to_sign.encode(),
        hashlib.sha256
    ).hexdigest()
    
    # Compare signatures
    if not hmac.compare_digest(signature, expected_signature):
        raise ValueError('Invalid signature')
    
    return True

@app.route('/webhooks/txncheck', methods=['POST'])
def webhook_handler():
    signature = request.headers.get('X-Webhook-Signature')
    timestamp = request.headers.get('X-Webhook-Timestamp')
    payload = request.json
    
    try:
        verify_webhook_signature(payload, signature, timestamp, WEBHOOK_SECRET)
        
        event = payload['event']
        data = payload['data']
        print(f"Received {event} for request {data['requestId']}")
        
        if event == 'request.completed':
            handle_verification_complete(data)
        elif event == 'request.failed':
            handle_verification_failed(data)
        elif event == 'request.partial':
            handle_partial_verification(data)
        
        return jsonify({'received': True}), 200
    except ValueError as e:
        return jsonify({'error': str(e)}), 400

<?php
function verifyWebhookSignature($payload, $signature, $timestamp, $secret) {
    // Reject old timestamps (> 5 minutes)
    $currentTime = time() * 1000;
    if (abs($currentTime - (int)$timestamp) > 300000) {
        throw new Exception('Timestamp too old');
    }
    
    // Calculate expected signature
    $payloadToSign = $timestamp . '.' . json_encode($payload);
    $expectedSignature = hash_hmac('sha256', $payloadToSign, $secret);
    
    // Compare signatures
    if (!hash_equals($signature, $expectedSignature)) {
        throw new Exception('Invalid signature');
    }
    
    return true;
}

// Handle incoming webhook
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$timestamp = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? '';
$payload = json_decode(file_get_contents('php://input'), true);

try {
    verifyWebhookSignature($payload, $signature, $timestamp, WEBHOOK_SECRET);
    
    $event = $payload['event'];
    $data = $payload['data'];
    
    switch ($event) {
        case 'request.completed':
            handleVerificationComplete($data);
            break;
        case 'request.failed':
            handleVerificationFailed($data);
            break;
        case 'request.partial':
            handlePartialVerification($data);
            break;
    }
    
    http_response_code(200);
    echo json_encode(['received' => true]);
} catch (Exception $e) {
    http_response_code(400);
    echo json_encode(['error' => $e->getMessage()]);
}

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "encoding/json"
    "fmt"
    "math"
    "net/http"
    "strconv"
    "time"
)

func verifyWebhookSignature(payload []byte, signature string, timestamp string, secret string) error {
    // Reject old timestamps (> 5 minutes)
    ts, _ := strconv.ParseInt(timestamp, 10, 64)
    currentTime := time.Now().UnixMilli()
    if math.Abs(float64(currentTime-ts)) > 300000 {
        return fmt.Errorf("timestamp too old")
    }

    // Calculate expected signature
    payloadToSign := fmt.Sprintf("%s.%s", timestamp, string(payload))
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(payloadToSign))
    expectedSignature := hex.EncodeToString(mac.Sum(nil))

    // Compare signatures
    if !hmac.Equal([]byte(signature), []byte(expectedSignature)) {
        return fmt.Errorf("invalid signature")
    }

    return nil
}

func webhookHandler(w http.ResponseWriter, r *http.Request) {
    signature := r.Header.Get("X-Webhook-Signature")
    timestamp := r.Header.Get("X-Webhook-Timestamp")

    var payload map[string]interface{}
    json.NewDecoder(r.Body).Decode(&payload)
    payloadBytes, _ := json.Marshal(payload)

    if err := verifyWebhookSignature(payloadBytes, signature, timestamp, webhookSecret); err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }

    event := payload["event"].(string)
    data := payload["data"].(map[string]interface{})
    fmt.Printf("Received %s for request %s\n", event, data["requestId"])

    w.WriteHeader(http.StatusOK)
    json.NewEncoder(w).Encode(map[string]bool{"received": true})
}

Retry Policy

If webhook delivery fails (non-2xx response or timeout), TxnCheck retries with exponential backoff:

Attempt	Delay
1	Immediate
2	1 second
3	2 seconds
4	4 seconds
5	8 seconds

After 5 failed attempts, the webhook is marked as failed. You can still retrieve results using the Request Status endpoint.

Testing Webhooks

Local Development

For local development, use a tunneling service like ngrok to expose your local server:

# Start ngrok
ngrok http 3000

# Use the ngrok URL for your webhook endpoint
# https://abc123.ngrok.io/webhooks/txncheck

Webhook Logs

View webhook delivery logs in the Merchant Dashboard under Webhooks → Logs. You can see:

Delivery status (success/failed)
Response codes
Retry attempts
Payload details

Best Practices

Always Verify Signatures

Never process webhooks without verifying the signature first

Respond Quickly

Return 200 immediately, process events asynchronously

Handle Duplicates

Use request ID for idempotency - you may receive the same event twice

Log Everything

Log webhook payloads for debugging and audit trails

Webhook endpoints must be publicly accessible HTTPS URLs. Self-signed certificates are not supported.

​Webhooks Guide

​How Webhooks Work

​Setting Up Webhooks

​Requirements

​Webhook Events

​Webhook Payload

​Payload Fields

​Full Check Step Statuses

​Webhook Headers

​Signature Verification

​Verification Algorithm

​Implementation Examples

​Retry Policy

​Testing Webhooks

​Local Development

​Webhook Logs

​Best Practices

Always Verify Signatures

Respond Quickly

Handle Duplicates

Log Everything

Webhooks Guide

How Webhooks Work

Setting Up Webhooks

Requirements

Webhook Events

Webhook Payload

Payload Fields

Full Check Step Statuses

Webhook Headers

Signature Verification

Verification Algorithm

Implementation Examples

Retry Policy

Testing Webhooks

Local Development

Webhook Logs

Best Practices