Developers

Webhooks

Wolet POSTs a signed JSON event to your HTTPS endpoint as things happen.

Event types

EventWhen
payment.detectedA paired phone read a payment notification
payment.confirmedA merchant confirmed a detection
payment.rejectedA merchant rejected a detection
reconciliation.updatedA reconciliation case changed
device.offlineNo heartbeat for 5 minutes
device.onlineHeartbeat resumed

Sample payload

json
{
  "id": "evt_01JD8X2K7Q",
  "type": "payment.detected",
  "created_at": "2026-11-17T14:32:08+05:30",
  "data": {
    "amount": 2450.00,
    "currency": "INR",
    "provider": "phonepe_business",
    "payer_name": "Ravi K.",
    "utr": "412839057216",          // null when the notification has no UTR
    "device_id": "dev_01",
    "branch_id": "br_1",
    "status": "detected",           // detected | confirmed | rejected | review
    "source": "android_notification",
    "verified_by_bank": false
  }
}

Verifying signatures

Each request carries Wolet-Signature: t=timestamp,v1=hex. Compute HMAC-SHA256 of {t}.{raw_body} with your endpoint's signing secret and compare in constant time. Reject requests older than 5 minutes.

javascript
import crypto from "node:crypto";
export function verify(raw, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const mac = crypto.createHmac("sha256", secret).update(`${t}.${raw}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(v1));
}

Retries

Any non-2xx response or a timeout over 10 seconds is retried with exponential backoff for up to 24 hours (8 attempts). Respond quickly and process asynchronously. Events can arrive more than once — de-duplicate by id.