Build / Webhooks
Webhooks
Vukia sends an HTTPS POST to your server each time an order changes status. Each request is signed with a secret that only you and Vukia know.
Set your endpoint
/v1/webhookcurl https://api.vukia.app/v1/webhook \
-H "Authorization: Bearer $VUKIA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://pos.example.com/hooks/vukia"}'
{
"url": "https://pos.duka.example/hooks/vukia",
"secret": "whsec_nyi_v_wRapSNWzHTGdDwgiJM7glriEUyQ6c8Y6Hf6pI",
"created_at": "2026-11-19T09:30:00.000Z"
}
The secret is returned only here. Calling this endpoint again replaces the URL and issues a new secret, and the old secret stops being used at once. GET /v1/webhook shows the current URL. DELETE /v1/webhook removes it.
The URL must:
- use
https://on port 443, with a certificate that public browsers trust; - use a public host name, not an IP address,
localhostor an internal name; - contain no username or password, and be no longer than 500 characters.
Vukia checks the host's address again on every delivery and refuses private and internal networks.
Event types
| Type | Sent when |
|---|---|
order.processing | The M-Pesa payment is confirmed and delivery has started. |
order.completed | The sats were delivered. Final. |
order.payment_failed | The customer did not pay. No money was taken. Final. |
order.needs_review | The customer paid but delivery could not be confirmed. Do not create a replacement order. |
ping | You called POST /v1/webhook/test. |
There is no event for order creation, because the create response already tells you. Vukia checks open orders every few seconds. A fast order can therefore go straight from awaiting_payment to order.completed without an order.processing event. Write your handler so that any event can arrive first.
The request
Content-Type: application/json
User-Agent: Vukia-Webhooks/1
Vukia-Event-Id: evt_d45b30b87df8dd641ee6f8e1
Vukia-Signature: t=1795080608,v1=229b155d2f3edb610c3a9104fdfce891fcb39da7448d4b62e00e1dbaca1b9b2a
{
"id": "evt_d45b30b87df8dd641ee6f8e1",
"object": "event",
"type": "order.completed",
"environment": "sandbox",
"created_at": "2026-11-19T09:30:08.000Z",
"data": {
"object": {
"id": "test_80ef637b4dada3da1c2a5fb70c4f9038",
"object": "order",
"environment": "sandbox",
"status": "completed",
"reference": "till-3-000187",
"amount": 150000,
"currency": "KES",
"fee": 4500,
"sats": 14550,
"kes_per_btc": 10000000,
"payment": {
"method": "mpesa_prompt",
"phone": "+254•••000",
"instructions": null,
"paybill": null
},
"destination": {
"lightning_address": "sh•••@blink.sv"
},
"delivery": {
"payment_hash": "ce478fbc0a2df281a8ebd57c4154a5f9e8a9fac5a0030e595a0720ca66e7150b",
"routing_fee_sats": 0
},
"failure": null,
"metadata": {
"till": "3",
"cashier": "wanjiru"
},
"created_at": "2026-11-19T09:30:00.000Z",
"updated_at": "2026-11-19T09:30:08.000Z"
}
}
}
The body is an event object. data.object is the full order as it was when the event was created.
Verify the signature
Vukia-Signature holds a Unix timestamp t and a signature v1. v1 is the hex HMAC-SHA256 of the string {t}.{raw body}, keyed with your webhook secret. To check it:
- Use the raw body bytes. Compute the signature before you parse the JSON. Re-encoded JSON will not match.
- Compute
HMAC_SHA256(secret, t + "." + body)and compare it withv1using a constant-time comparison. - Reject old timestamps. Refuse anything more than 5 minutes from your clock. Each retry is signed again with a fresh timestamp.
// Express. The route must receive the raw body, not parsed JSON.
import express from 'express';
import { createHmac, timingSafeEqual } from 'node:crypto';
const app = express();
app.post('/hooks/vukia', express.raw({ type: 'application/json' }), async (req, res) => {
const parts = Object.fromEntries((req.get('Vukia-Signature') || '').split(',').map(p => p.split('=')));
const t = Number(parts.t);
if (!parts.v1 || !Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > 300) return res.sendStatus(400);
const expected = createHmac('sha256', process.env.VUKIA_WEBHOOK_SECRET)
.update(`${parts.t}.`).update(req.body).digest();
const given = Buffer.from(parts.v1, 'hex');
if (given.length !== expected.length || !timingSafeEqual(given, expected)) return res.sendStatus(400);
const event = JSON.parse(req.body);
await recordEvent(event); // your code: store it, ignore duplicates by event.id
res.sendStatus(200); // answer within 10 seconds; do slow work afterwards
});
# Flask
import hashlib, hmac, json, os, time
from flask import Flask, abort, request
app = Flask(__name__)
@app.post("/hooks/vukia")
def vukia_webhook():
raw = request.get_data() # raw bytes, before any JSON parsing
parts = dict(p.split("=", 1) for p in request.headers.get("Vukia-Signature", "").split(",") if "=" in p)
try:
t = int(parts["t"])
except (KeyError, ValueError):
abort(400)
if abs(time.time() - t) > 300:
abort(400)
signed = parts["t"].encode() + b"." + raw
expected = hmac.new(os.environ["VUKIA_WEBHOOK_SECRET"].encode(), signed, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, parts.get("v1", "")):
abort(400)
event = json.loads(raw)
record_event(event) # your code: store it, ignore duplicates by event["id"]
return "", 200
<?php
$raw = file_get_contents('php://input'); // raw body
$parts = [];
foreach (explode(',', $_SERVER['HTTP_VUKIA_SIGNATURE'] ?? '') as $p) {
[$k, $v] = array_pad(explode('=', $p, 2), 2, '');
$parts[$k] = $v;
}
$t = $parts['t'] ?? '';
if (!ctype_digit($t) || abs(time() - (int) $t) > 300) {
http_response_code(400);
exit;
}
$expected = hash_hmac('sha256', $t . '.' . $raw, getenv('VUKIA_WEBHOOK_SECRET'));
if (!hash_equals($expected, $parts['v1'] ?? '')) {
http_response_code(400);
exit;
}
$event = json_decode($raw, true);
record_event($event); // your code: store it, ignore duplicates by $event['id']
http_response_code(200);
To test your check, send a ping with POST /v1/webhook/test. The response tells you what HTTP status your endpoint returned.
Handling events correctly
- Answer quickly. Return any
2xxwithin 10 seconds. Store the event and do slow work, such as printing or sending messages, afterwards. A slow response counts as a failure and is retried. - Expect duplicates. An event can arrive more than once, for example if your server timed out after storing it. Ignore an
idyou have already processed. The same ID is in theVukia-Event-Idheader. - Expect any order. Retries can make an older event arrive after a newer one. Act on the order's status, and never move a sale backwards: once a sale is
completed, a lateorder.processingmust not reopen it. - Redirects are failures. Vukia does not follow
3xxresponses. Register the final URL. - When in doubt, ask the API.
GET /v1/orders/{id}always returns the current status.
Retries
If your endpoint does not answer with a 2xx within 10 seconds, Vukia tries again. There are 7 attempts in all, spread over about 20 hours:
| Attempt | Waits after the previous attempt |
|---|---|
| 1 | Sent immediately |
| 2 | 1 minute |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
| 6 | 6 hours |
| 7 | 12 hours |
After the 7th failure the event is marked failed and is not sent again. It stays in the events log.
Events are only sent to an endpoint that was registered when the event happened. If you had no endpoint, the event is logged with the state no_endpoint.
The events log
/v1/eventsEvery event for your account, newest first, with its delivery state. Use it to catch up after an outage, or to find out why a webhook did not arrive. Parameters: limit (1 to 100, default 20), starting_after (an event id) and type (for example order.completed).
Each event in the list is the same object your endpoint receives, plus a delivery field:
{
"state": "delivered",
"attempts": 1,
"last_status": 200,
"last_error": null
}
delivery.state | Meaning |
|---|---|
pending | Not delivered yet. Another attempt is scheduled. |
delivered | Your endpoint returned 2xx. |
failed | All 7 attempts failed. |
no_endpoint | No webhook URL was set when the event happened. |
last_status is the HTTP status your server last returned, if any. last_error is one of http_<status>, timeout, connection_failed or blocked_address (your host resolved to a private address).
A simple safety net: once an hour, page through GET /v1/events?type=order.completed back to your last processed event, and apply any you missed.
Rotating the secret
Call POST /v1/webhook again with the same URL. The response holds a new secret, and every event from then on, including retries of older events, is signed with it. To avoid rejecting events during the switch, briefly accept either the old or the new secret, then remove the old one.