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
| Event | Sent when |
|---|---|
bill.successful | A payment was delivered (prepaid electricity carries the token) |
bill.failed | A payment could not be delivered; your wallet was refunded |
bill.reversed | A 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:
- Compute the HMAC over the raw body bytes, not over re-serialised JSON.
- Compare in constant time.
- Refuse messages whose
tis more than 5 minutes old.
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);
});
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}.