API

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

POST/v1/webhook
curl 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:

Vukia checks the host's address again on every delivery and refuses private and internal networks.

Event types

TypeSent when
order.processingThe M-Pesa payment is confirmed and delivery has started.
order.completedThe sats were delivered. Final.
order.payment_failedThe customer did not pay. No money was taken. Final.
order.needs_reviewThe customer paid but delivery could not be confirmed. Do not create a replacement order.
pingYou 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:

  1. Use the raw body bytes. Compute the signature before you parse the JSON. Re-encoded JSON will not match.
  2. Compute HMAC_SHA256(secret, t + "." + body) and compare it with v1 using a constant-time comparison.
  3. 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

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:

AttemptWaits after the previous attempt
1Sent immediately
21 minute
35 minutes
430 minutes
52 hours
66 hours
712 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

GET/v1/events

Every 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.stateMeaning
pendingNot delivered yet. Another attempt is scheduled.
deliveredYour endpoint returned 2xx.
failedAll 7 attempts failed.
no_endpointNo 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.