Skip to main content

Webhooks

When a payment settles, Vmonie POSTs it to your webhook URL, so you don't have to poll for PENDING payments.

Setting up​

Under Developers → Webhook in the dashboard, enter an https URL on your server. The first time, the dashboard shows your signing secret (starts with whsec_) once. Store it like a password. If it leaks, rotate it there; the old secret stops working at once.

Send test webhook posts a webhook.test event to your URL straight away and shows what your server answered. Its data is { "message": "This is a test webhook from Vmonie." }. A test is never retried.

The dashboard also lists recent deliveries, with their status and your server's last answer, and can resend a failed one.

Events​

EventSent when
bill.successfulA payment was delivered (prepaid electricity carries the token)
bill.failedA payment could not be delivered; your wallet was refunded
bill.reversedA delivered payment was reversed by the biller; your wallet was refunded

A payment that is final in the pay response (SUCCESSFUL or FAILED) still gets its webhook too, so you can handle every outcome in one place.

The request​

POST /your/webhook HTTP/1.1
Content-Type: application/json
Vmonie-Event: bill.successful
Vmonie-Delivery: 3f0c9a1e-…
Vmonie-Signature: t=1763294400,v1=5d41402abc4b2a76b9719d911017c592…
{
"id": "3f0c9a1e-…",
"event": "bill.successful",
"createdAt": "2026-11-16T12:00:00.000Z",
"data": {
"reference": "VMB…",
"idempotencyKey": "order-10024-power",
"status": "SUCCESSFUL",
"type": "ELECTRICITY",
"customerIdentifier": "45031234567",
"amountMinor": "500000",
"totalMinor": "510000",
"token": "1234-5678-9012-3456-7890"
}
}

data has the same shape as GET /bills/{reference}.

Verifying the signature​

Vmonie-Signature is t=<unix seconds>,v1=<hex>, where v1 is the HMAC-SHA256 of "<t>.<raw request body>" keyed with your signing secret. Check it before trusting the message:

  1. Compute the HMAC over the raw body bytes, not over re-serialised JSON.
  2. Compare in constant time.
  3. Refuse messages whose t is more than 5 minutes old.
Node.js (Express)
const crypto = require('crypto');

app.post('/webhooks/vmonie', express.raw({ type: 'application/json' }), (req, res) => {
const header = req.get('Vmonie-Signature') || '';
const [, t, v1] = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header) || [];
const expected = crypto
.createHmac('sha256', process.env.VMONIE_WEBHOOK_SECRET)
.update(`${t}.${req.body}`)
.digest('hex');
const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
if (!v1 || !fresh || !crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected))) {
return res.sendStatus(400);
}
const event = JSON.parse(req.body);
// … handle event.event / event.data, keyed on event.id …
res.sendStatus(200);
});
Python (Flask)
import hmac, hashlib, os, re, time
from flask import request, abort

@app.post("/webhooks/vmonie")
def vmonie_webhook():
m = re.fullmatch(r"t=(\d+),v1=([0-9a-f]{64})", request.headers.get("Vmonie-Signature", ""))
if not m:
abort(400)
t, v1 = m.groups()
body = request.get_data() # raw bytes
expected = hmac.new(os.environ["VMONIE_WEBHOOK_SECRET"].encode(),
f"{t}.".encode() + body, hashlib.sha256).hexdigest()
if abs(time.time() - int(t)) > 300 or not hmac.compare_digest(v1, expected):
abort(400)
event = request.get_json()
# … handle event["event"] / event["data"], keyed on event["id"] …
return "", 200

Answering and retries​

Reply with any 2xx within 10 seconds. Do the slow work after replying. Anything else (an error status, a timeout or a redirect) counts as a failure, and Vmonie retries after 1 minute, 5 minutes, 15 minutes, 1 hour, 3 hours, 6 hours, 12 hours and 24 hours, then stops. You can resend a stopped webhook from the dashboard.

A message can arrive more than once. Use id (also in Vmonie-Delivery) to ignore repeats. Messages can also arrive out of order, so if you have missed some, the bill's latest state is always at GET /bills/{reference}.