TukuPay Docs

Follow payments

Webhooks

Optional: TukuPay POSTs payment events to your server, signed with your webhook signing secret.

Set up

  1. On the app's page, set a webhook URL: public https, e.g. https://shop.example.com/tukupay/webhook (needs your PIN).
  2. Put the webhook signing secret in TUKUPAY_WEBHOOK_SECRET on that server.
  3. Press Send test event, or call POST /v1/webhooks/test, and check your endpoint answers 2xx.

Events

EventWhen
payment.completedA payment made through the app completed
payment.failedIt failed
payment.reversedA completed payment was reversed
collection.prompt_answeredThe payer answered an M-Pesa prompt (answered: paid or not_paid)
payout.awaiting_approvalMoney out is waiting for the account holder
payout.approved, payout.declinedThey approved it, or declined it (or it expired)
test.pingA test event you asked for

The request

A POST with JSON body { id, type, created_at, livemode, app_id, data }. data is the payment (reference, external_reference, status, kind, amount, bank_charges, currency, wallet_id, customer_id, failure_reason, completed_at, created_at). Headers: Tuku-Signature (and Tuku-Signature-Previous for 24 hours after you replace the secret), Tuku-Event-Id, Tuku-Event-Type, Tuku-Timestamp, Tuku-Delivery-Id.

Check the signature, every time

Tuku-Signature: t=<unix>,v1=<hex>, where hex is HMAC-SHA256 with your webhook signing secret of <t>.<raw body>. Check it on the raw body (before any JSON parsing), in constant time, and refuse a t more than 5 minutes old.

import crypto from "node:crypto";

// true when Tuku-Signature (or, for 24 hours after you replace the secret, Tuku-Signature-Previous) checks with your secret
export function verifyTukuWebhook(rawBody, headers, secret) {
  return [headers["tuku-signature"], headers["tuku-signature-previous"]].some((header) => {
    const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header || "");
    if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false;
    const want = crypto.createHmac("sha256", secret).update(m[1] + "." + rawBody).digest();
    return crypto.timingSafeEqual(Buffer.from(m[2], "hex"), want);
  });
}

// Express: keep the raw body for this route
app.post("/tukupay/webhook", express.raw({ type: "application/json" }), (req, res) => {
  if (!verifyTukuWebhook(req.body.toString("utf8"), req.headers, process.env.TUKUPAY_WEBHOOK_SECRET)) return res.status(400).end();
  const event = JSON.parse(req.body);
  // skip repeats by event.id, then handle event.type
  res.status(200).end();
});

Delivery and retries

  • Answer 2xx within 5 seconds; do slow work afterwards. Anything else is retried 8 times, waiting 30 seconds and doubling each time (a little over an hour in all).
  • The same event may arrive more than once, or out of order: use id to skip repeats, and trust the status in data.
  • At most 500 deliveries wait per app; past that, new events are logged as failed until your endpoint is fixed (then resend them).
  • Every attempt is logged on the app's page with what was sent and the start of your answer; there you can Resend and Send test event.

Changing the signing secret (rotation)

  1. On the app's page, Webhooks → Signing secret → Replace signing secret, with your PIN. Copy the new secret (shown once).
  2. For the next 24 hours every webhook carries two signatures: Tuku-Signature with the new secret and Tuku-Signature-Previous with the old one, so your server keeps working while it still has the old secret (the code above checks both).
  3. Within those 24 hours, put the new secret in TUKUPAY_WEBHOOK_SECRET and redeploy. Send a test event to check.

Your webhook URL

Public https only. Private, loopback, link-local and internal addresses are refused when you save the URL and again before each send. Redirects are not followed. Changing the URL needs your PIN.

From the API

GET/v1/webhooks/deliveriesSigned · own app

SeeSigning requestsErrors

The app's deliveries, newest first: status (pending, delivered, failed), limit (1 to 100), offset. Answers { items }, each with id, event_id, event_type, livemode, url, status, attempts, response_status, last_error, delivered_at, is_test, resend and created_at (bodies are on the app's page).

POST/v1/webhooks/testSigned · own app

SeeSigning requestsErrors

Sends test.ping to your webhook URL and answers the new delivery. 10 test events and resends a minute per app. Neither call takes Tuku-Customer.