Follow payments
Webhooks
Optional: TukuPay POSTs payment events to your server, signed with your webhook signing secret.
Set up
- On the app's page, set a webhook URL: public
https, e.g.https://shop.example.com/tukupay/webhook(needs your PIN). - Put the webhook signing secret in
TUKUPAY_WEBHOOK_SECRETon that server. - Press Send test event, or call
POST /v1/webhooks/test, and check your endpoint answers2xx.
Events
| Event | When |
|---|---|
payment.completed | A payment made through the app completed |
payment.failed | It failed |
payment.reversed | A completed payment was reversed |
collection.prompt_answered | The payer answered an M-Pesa prompt (answered: paid or not_paid) |
payout.awaiting_approval | Money out is waiting for the account holder |
payout.approved, payout.declined | They approved it, or declined it (or it expired) |
test.ping | A 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
2xxwithin 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
idto skip repeats, and trust thestatusindata. - 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)
- On the app's page, Webhooks → Signing secret → Replace signing secret, with your PIN. Copy the new secret (shown once).
- For the next 24 hours every webhook carries two signatures:
Tuku-Signaturewith the new secret andTuku-Signature-Previouswith the old one, so your server keeps working while it still has the old secret (the code above checks both). - Within those 24 hours, put the new secret in
TUKUPAY_WEBHOOK_SECRETand 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
/v1/webhooks/deliveriesSigned · own appThe 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).
/v1/webhooks/testSigned · own appSends 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.