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
1
Submit Request
You submit a verification request (e.g., UPI by Mobile)
2
Request Queued
API returns
202 Accepted with a request ID3
Processing
TxnCheck processes the verification request
4
Webhook Delivered
Results are sent to your configured webhook URL
5
Confirmation
Your server returns
2xx to acknowledge receiptSetting 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
2xxwithin 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: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
Forfull-check requests, the stepStatuses field shows the outcome of each verification step:
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
Verification Algorithm
Implementation Examples
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 |
Testing Webhooks
Local Development
For local development, use a tunneling service like ngrok to expose your local server: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.
